דף זה תורגם על ידי Cloud Translation API.

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

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

Pete LePage

מהו ה-API getInstalledRelatedApps()‎?

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

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

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

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

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

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

סוג האפליקציה	אפשר לבדוק את זה מ-
אפליקציה ל-Android	Android בלבד Chrome 80 ואילך
אפליקציה ל-Windows‏ (UWP)	Windows בלבד Chrome מגרסה 85 ואילך Edge מגרסה 85 ואילך
אפליקציית Progressive Web App שמותקנת באותו היקף או בהיקף אחר.	Android בלבד Chrome 84 ואילך

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

איך בודקים אם אפליקציית 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 Store.

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

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

במאמר הפעלת אפליקציות לאתרים באמצעות בוררים של URI של אפליקציות מוסבר בפירוט איך מגדירים בוררים של 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 מותקנת.

בדיקה אם אפליקציית ה-Progressive Web App כבר מותקנת (בטווח ההיקף)

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

נתמכת בפלטפורמות

Android: ‏ Chrome 84 ואילך

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

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

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

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

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

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

הדגמה

בדיקה אם אפליקציית 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"
    }
  }
]

הערה: חשוב לבדוק שוב את שם הקובץ כשיוצרים את הקובץ assetlinks.json. הקדשתי שעות רבות לניפוי באגים, רק כדי להבין שהוספת 's' נוסף לשם הקובץ.

דיווח על אפליקציית ה-PWA באתר

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

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

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

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

לבסוף, קוראים את ה-URL 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. Glitch הוא כלי מצוין לשיתוף שחזור מהיר וקל של באגים.

תמיכה ב-API

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

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

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

תודה

תודה מיוחדת ל-Sunggook Chue מ-Microsoft על העזרה בפרטים לבדיקת אפליקציות ל-Windows, ותודה ל-Rayan Kanso על העזרה בפרטים לגבי Chrome.