האם האפליקציה שלך מותקנת? תקבל הודעה מ-getInstalledRelatedApps() !

השיטה getInstalledRelatedApps() מאפשרת לאתר שלכם לבדוק אם אפליקציית Android/UWP או PWA מותקנת במכשיר של המשתמש.

Pete LePage

Alexey Rodionov

מה זה getInstalledRelatedApps() API?

השיטה getInstalledRelatedApps() מחזירה את רשימת האפליקציות הקשורות שהותקנו.

הקריאה ל-navigator.getInstalledRelatedApps() מחזירה הבטחה (promise) שמושלמת עם מערך של אפליקציות קשורות שמותקנות במכשיר של המשתמש.

const relatedApps = await navigator.getInstalledRelatedApps();
relatedApps.forEach((app) => {
  console.log(app.id, app.platform, app.url);
});

היא מאפשרת לדף שלכם לבדוק אם אפליקציית Android שלכם, אפליקציית Universal Windows Platform ‏ (UWP) או אפליקציית Progressive Web App ‏ (PWA) כבר מותקנת במכשיר של המשתמש, ומאפשרת לכם להתאים אישית את חוויית המשתמש אם היא מותקנת.

לדוגמה, אם האפליקציה כבר מותקנת:

• הפניית המשתמש מדף שיווקי של מוצר ישירות לאפליקציה.
• ריכוז של פונקציות מסוימות, כמו התראות, באפליקציה השנייה כדי למנוע התראות כפולות.
• לא מקדם את ההתקנה של ה-PWA אם האפליקציה האחרת כבר מותקנת.

סוגי האפליקציות הנתמכות שאפשר לבדוק

איך בודקים אם אפליקציית Android מותקנת

האתר שלכם יכול לבדוק אם אפליקציית Android שלכם מותקנת.

איך מעדכנים את האפליקציה ל-Android לגבי האתר

קודם כול, צריך לעדכן את אפליקציית Android כדי להגדיר את הקשר בין האתר לבין אפליקציית Android באמצעות מערכת Digital Asset Links. כך מוודאים שרק האתר שלכם יכול לבדוק אם אפליקציית Android שלכם מותקנת.

ב-AndroidManifest.xml של אפליקציית Android, מוסיפים רשומה של asset_statements:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

לאחר מכן, בקטע strings.xml, מוסיפים את הצהרת הנכס הבאה ומעדכנים את site בדומיין שלכם. חשוב לכלול את התווים לביטול בריחה.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

אחרי שתסיימו, תצטרכו להתקין את האפליקציה המעודכנת במכשיר או לפרסם אותה בחנות Google Play או בכל אחת מהפלטפורמות האחרות להפצת אפליקציות ל-Android.

איך מעדכנים את האתר לגבי האפליקציה ל-Android

בשלב הבא, צריך להוסיף לאתר מניפסט של אפליקציית אינטרנט כדי להודיע לאתר על אפליקציית Android. קובץ המניפסט צריך לכלול את המאפיין related_applications, מערך שמספק את הפרטים על האפליקציה, כולל platform ו-id.

• הערך של platform צריך להיות play
• ‫id הוא מזהה החבילה ל-Android

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

איך בודקים אם האפליקציה מותקנת

לבסוף, קוראים לפונקציה האסינכרונית navigator.getInstalledRelatedApps() כדי לבדוק אם אפליקציית Android מותקנת.

בדיקה אם אפליקציית Windows ‏ (UWP) מותקנת

האתר שלכם יכול לבדוק אם אפליקציית Windows (שנוצרה באמצעות UWP) מותקנת.

איך מעבירים לאפליקציית Windows מידע על האתר

כדי להגדיר את הקשר בין האתר שלכם לבין אפליקציית Windows, תצטרכו לעדכן את אפליקציית Windows באמצעות מטפלי URI. כך מוודאים שרק האתר שלכם יכול לבדוק אם אפליקציית Windows מותקנת.

מוסיפים את רישום התוסף Windows.appUriHandler לקובץ המניפסט של האפליקציה Package.appxmanifest. לדוגמה, אם כתובת האתר שלכם היא example.com, תוסיפו את הרשומה הבאה למניפסט של האפליקציה:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

הערה: יכול להיות שתצטרכו להוסיף את מרחב השמות uap3 למאפיין <Package>.

לאחר מכן, יוצרים קובץ JSON (בלי סיומת הקובץ .json) בשם windows-app-web-link ומזינים את שם חבילת האפליקציה. ממקמים את הקובץ בשורש השרת או בספרייה /.well-known/. אפשר למצוא את שם משפחת החבילה בקטע Packaging (אריזה) בכלי לעיצוב מניפסט האפליקציה.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

כדאי לעיין בהדגמה הזו.

פרטים מלאים על הגדרת רכיבי handler של URI זמינים במאמר הפעלת אפליקציות לאתרים באמצעות רכיבי handler של URI.

איך מספרים לאתר על אפליקציית Windows

בשלב הבא, צריך לספר לאתר על אפליקציית Windows שלכם על ידי הוספת מניפסט של אפליקציית אינטרנט לדף. המניפסט צריך לכלול את המאפיין related_applications, מערך שמספק את הפרטים על האפליקציה, כולל platform ו-id.

• הערך של platform צריך להיות windows
• ‫id הוא שם משפחת החבילה של האפליקציה, שמוסף לו הערך <Application> Id בקובץ Package.appxmanifest.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

איך בודקים אם האפליקציה מותקנת

לבסוף, קוראים לפונקציה האסינכרונית navigator.getInstalledRelatedApps() כדי לבדוק אם אפליקציית Windows מותקנת.

בדיקה אם אפליקציית האינטרנט המתקדמת כבר מותקנת (במסגרת)

אפליקציית ה-PWA יכולה לבדוק אם היא כבר מותקנת. במקרה כזה, הדף ששולח את הבקשה צריך להיות באותו דומיין, ובהיקף של ה-PWA, כפי שמוגדר בהיקף במניפסט של אפליקציית האינטרנט.

איך מספרים לאפליקציית PWA על עצמה

כדי להוסיף מידע על ה-PWA, מוסיפים רשומה של related_applications אל מניפסט אפליקציית האינטרנט של ה-PWA.

• הערך של platform צריך להיות webapp
• ‫url הוא הנתיב (יכול להיות יחסי) למניפסט של אפליקציית האינטרנט של ה-PWA
• ‫id הוא הנתיב המלא לאפליקציית האינטרנט (נדרש למחשב, לא נדרש ל-Android)

{
  …
  "scope": "/",
  "start_url": "/",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com"
  }],
  …
}

איך בודקים אם אפליקציית ה-PWA מותקנת

לבסוף, קוראים לפונקציה האסינכרונית navigator.getInstalledRelatedApps() מתוך ההיקף של ה-PWA כדי לבדוק אם הוא מותקן. אם הפונקציה getInstalledRelatedApps() נקראת מחוץ להיקף של אפליקציית ה-PWA, היא תחזיר []. למידע נוסף, עיין בקטע הבא.

בדיקה אם ה-PWA מותקן (לא רלוונטי)

האתר שלכם יכול לבדוק אם אפליקציית ה-PWA מותקנת, גם אם הדף נמצא מחוץ לטווח של אפליקציית ה-PWA. לדוגמה, דף נחיתה שמוצג מ-/landing/ יכול לבדוק אם אפליקציית ה-PWA שמוצגת מ-/pwa/ מותקנת, או אם דף הנחיתה מוצג מ-www.example.com ואפליקציית ה-PWA מוצגת מ-app.example.com.

איך מספרים לאפליקציית ה-PWA על האתר

קודם כול, צריך להוסיף קישורים לנכסים דיגיטליים לשרת שממנו מוגש ה-PWA. הפעולה הזו תעזור להגדיר את הקשר בין האתר לבין אפליקציית ה-PWA, ותאמת שרק האתר יוכל לבדוק אם אפליקציית ה-PWA מותקנת.

מוסיפים קובץ assetlinks.json לתיקייה /.well-known/ של הדומיין שבו נמצא ה-PWA, לדוגמה app.example.com. במאפיין site, מציינים את הנתיב המלא למניפסט של אפליקציית האינטרנט שתבצע את הבדיקה (לא המניפסט של אפליקציית האינטרנט מסוג PWA).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

איך מספרים לאתר על ה-PWA

בשלב הבא, צריך לספר לאתר על אפליקציית ה-PWA על ידי הוספת מניפסט של אפליקציית אינטרנט לדף. המניפסט צריך לכלול את המאפיין related_applications, מערך שמספק את הפרטים על ה-PWA, כולל platform ו-url.

• הערך של platform צריך להיות webapp
• ‫url הוא הנתיב המלא למניפסט של אפליקציית האינטרנט של ה-PWA

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

איך בודקים אם אפליקציית ה-PWA מותקנת

לבסוף, קוראים לפונקציה האסינכרונית navigator.getInstalledRelatedApps() כדי לבדוק אם אפליקציית ה-PWA מותקנת.

עדיין יש לכם שאלות?

עדיין יש לכם שאלות? כדאי לבדוק את התג getInstalledRelatedApps ב-StackOverflow כדי לראות אם למישהו אחר היו שאלות דומות. אם לא, אפשר לפרסם את השאלה שם ולתייג אותה בתג progressive-web-apps. הצוות שלנו עוקב אחרי התיוג הזה ומנסה לענות על השאלות שלכם.

משוב

מצאתם באג בהטמעה של Chrome? או שההטמעה שונה מהמפרט?

• מדווחים על באג בכתובת https://new.crbug.com. חשוב לכלול כמה שיותר פרטים, לספק הוראות לשחזור הבאג ולהזין Mobile>WebAPKs בתיבה Components (רכיבים).

תמיכה ב-API

האם בכוונתך להשתמש ב-getInstalledRelatedApps() API? התמיכה הציבורית שלכם עוזרת לצוות Chrome לקבוע את סדר העדיפויות של התכונות, ומראה לספקי דפדפנים אחרים עד כמה חשוב לתמוך בהן.

• משתפים את התוכניות שלכם לגבי השימוש ב-API בשרשור ב-WICG Discourse.
• אתם יכולים לשלוח ציוץ אל @ChromiumDev באמצעות ההאשטאג #getInstalledRelatedApps ולספר לנו איפה ואיך אתם משתמשים בו.

קישורים שימושיים

• הסבר ציבורי על getInstalledRelatedApps() API
• Spec draft
• באג במעקב
• ערך ב-ChromeStatus.com
• רכיב Blink: ‏ Mobile>WebAPKs

תודה

תודה מיוחדת לסונגוק צ'ו ממיקרוסופט על העזרה בפרטים לבדיקת אפליקציות Windows, ולרייאן קנסו על העזרה בפרטים של Chrome.