האם האפליקציה מותקנת? ממשק ה-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() מחזירה הבטחה שמושלמת עם מערך של אובייקטים שמכילים פרטים על אפליקציות שהן:

  • מותקנת במכשיר הנוכחי,
  • מוגדר בשדה 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>

טיפ למתקדמים: זהו מערך. כלומר, אתם יכולים להגדיר קשר מאומת בין אפליקציית Android שלכם ליותר מאתר אחד.

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

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

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

  • הערך של platform צריך להיות play
  • ‫id הוא מזהה החבילה ל-Android
{
  ...
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.twa"
    }
  ]
  ...
}

טיפ למתקדמים: זהו מערך. כלומר, אתם יכולים להגדיר קשר מאומת בין האתר שלכם ליותר מאפליקציית Android אחת.

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

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

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

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

נתמך ב:

  • ב-Windows בלבד: Chrome מגרסה 85 ואילך, Edge מגרסה 85 ואילך

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

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

מוסיפים את רישום התוסף Windows.appUriHandler לקובץ המניפסט של האפליקציה AppxManifest.xml או 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>.

אם לאתר שלכם יש כמה כתובות, צריך להוסיף רשומה נפרדת <uap3:Host Name=... /> בתוך <uap3:AppUriHandler> לכל כתובת.

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

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

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

כדי לגלות את שם משפחת החבילה, אפשר להתקין את האפליקציה, להריץ את הפקודה הבאה ב-PowerShell ולמצוא את האפליקציה ברשימה:

Get-AppxPackage | Select-Object PackageFamilyName

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

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

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

  • הערך של platform צריך להיות windows
  • ‫id הוא שם משפחת החבילה של האפליקציה עם !App שנוסף כסיומת בסוף
{
  ...
  "related_applications": [
    {
      "platform": "windows",
      "id": "MyApp_9jmtgj1pbbz6e!App"
    }
  ]
  ...
}

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

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

לבסוף, קוראים לפונקציה האסינכרונית 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, היא תחזיר []. למידע נוסף, עיין בקטע הבא.

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

האתר שלכם יכול לבדוק אם אפליקציית ה-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

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

  • הערך של platform צריך להיות webapp
  • ‫url הוא הנתיב המלא לקובץ מניפסט של אפליקציה של אפליקציית האינטרנט של ה-PWA
{
  ...
  "related_applications": [
    {
      "platform": "webapp",
      "url": "https://app.example.com/manifest.json"
    }
  ]
  ...
}

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

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

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

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

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

משוב

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

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

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

תודה

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