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

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

Pete LePage
Alexey Rodionov
Alexey Rodionov
X GitHub LinkedIn

מה זה getInstalledRelatedApps() API?

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

התג getInstalledRelatedApps() מאפשר לדף שלכם לבדוק אם אפליקציית המובייל או הדסקטופ שלכם, או במקרים מסוימים, אם אפליקציית Progressive Web App ‏ (PWA) כבר מותקנת במכשיר של המשתמש, ומאפשר לכם להתאים אישית את חוויית המשתמש אם היא מותקנת.

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

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

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

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

סוג האפליקציה ניתן לבדוק מ-
אפליקציית Android ‫Android בלבד
‫Chrome 80 ואילך
אפליקציית Windows‏ (UWP) Windows בלבד
Chrome 85 ואילך
Edge 85 ואילך
‫Progressive Web App
הותקן באותו היקף או בהיקף אחר. 		‫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 המעודכנת בחנות Play.

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

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

  • הערך של platform צריך להיות play
  • ‫id הוא מזהה האפליקציה ב-Google Play לאפליקציה ל-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 ומזינים את שם חבילת האפליקציה. ממקמים את הקובץ בשורש השרת או בספרייה /.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, כפי שמוגדר בהיקף במניפסט של אפליקציית האינטרנט.

נתמך ב

‫Android: Chrome 84 ואילך

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

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

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

נתמך ב

‫Android: Chrome 84 ואילך

מחשב (Windows, ‏ macOS, ‏ Linux, ‏ ChromeOS): Chrome 140 ואילך

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

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

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

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

בדומה לרוב ממשקי ה-API העוצמתיים האחרים באינטרנט, ה-API של getInstalledRelatedApps() זמין רק כשמציגים אותו באמצעות HTTPS.

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

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

משוב

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

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

תמיכה ב-API

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

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

תודה

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