האם האפליקציה מותקנת? ממשק ה-API Get Installed Related Apps ייתן לכם את התשובה.

Pete LePage
Alexey Rodionov
Alexey Rodionov
X GitHub LinkedIn

Get Installed Related Apps API מאפשר לקבל את רשימת האפליקציות הקשורות המותקנות יחד עם פרטים עליהן.

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

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

לדוגמה:

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

מה זה Get Installed Related Apps API?

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

  • מותקנת במכשיר הנוכחי,
  • מוגדר בשדה related_applications של מניפסט אפליקציית האינטרנט,
  • יש לכם קשר מאומת עם דף שבו מופעלת השיטה navigator.getInstalledRelatedApps() (פרטים מופיעים בקטעים הבאים).
const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

התקשרות אל console.log(installedRelatedApps) מחזירה תגובה כמו:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

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

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

אם אתם יודעים את מזהה החבילה, כדי לקבל את מספר הגרסה של אפליקציית Android קשורה שהותקנה, אתם יכולים להשתמש בשורה הבאה:

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

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

סוג האפליקציה אפשר לבדוק מ-
באפליקציה ל-Android ‫Android בלבד:
Chrome 80 ואילך
אפליקציית Universal Windows Platform ‏ (UWP) ב-Windows בלבד:
Chrome 85 ואילך
Edge 85 ואילך
אפליקציית Progressive Web App ‏ (PWA) שהותקנה באותו היקף באותו מקור ‫Android:
Chrome 84 ואילך
מחשב (Windows, ‏ macOS, ‏ Linux, ‏ ChromeOS):
Chrome 140 ואילך
Edge 140 ואילך
אפליקציית Progressive Web App ‏ (PWA)
שהותקנה בהיקף שונה באותו מקור או במקור אחר 		‫Android בלבד:
Chrome 84 ואילך

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

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

נתמך ב:

  • ‫Android בלבד: Chrome 80 ואילך

איך מעדכנים את האפליקציה ל-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 בלבד: Chrome מגרסה 85 ואילך, Edge מגרסה 85 ואילך

איך מעבירים לאפליקציית 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 ומזינים את שם חבילת האפליקציה. ממקמים את הקובץ בספריית הבסיס (root) של השרת או בספרייה /.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, כפי שמוגדר בהיקף במניפסט של אפליקציית האינטרנט.

נתמך ב:

  • ‫Android: Chrome 84 ואילך
  • מחשב (Windows, ‏ macOS, ‏ Linux, ‏ ChromeOS): Chrome מגרסה 140 ואילך, Edge מגרסה 140 ואילך

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

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

  • הערך של platform צריך להיות webapp
  • ‫url הוא הנתיב (יכול להיות יחסי) למניפסט של אפליקציית האינטרנט של ה-PWA
  • ‫id הוא מזהה אפליקציית האינטרנט שמוצהר בשדה id של מניפסט אפליקציית האינטרנט או מחושב על ידי הדפדפן (נדרש למחשב, לא נדרש ל-Android)
{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

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

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

בדיקה אם Progressive Web App מותקן (לא רלוונטי)

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

נתמך ב:

  • ‫Android בלבד: Chrome 84 ואילך

איך מספרים לאפליקציית ה-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.

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

תודה

תודה מיוחדת לסונגוק צ'ו (Sunggook Chue) במיקרוסופט על העזרה בפרטים לבדיקת אפליקציות Windows, ולרייאן קנסו (Rayan Kanso) על העזרה בפרטים לגבי Chrome.