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

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

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

Pete LePage

מהו ה-API getInstalledRelatedApps()‎?

אתר שמשתמש ב-`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 ואילך

הערה: ממשק ה-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 הוא שם המשפחה של חבילת האפליקציה, שמוצמד לערך Id <Application> בקובץ 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 מותקנת

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

כדאי לנסות את ההדגמה

קריאה ל-getInstalled relatedApps()

קריאה ל-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.