אימות קישורים לאפליקציות ל-Android

קישור לאפליקציה ל-Android הוא סוג מיוחד של קישור עומק שמאפשר לכתובות ה-URL של האתר לפתוח באופן מיידי את התוכן התואם באפליקציה ל-Android, בלי שהמשתמש יצטרך לבחור את האפליקציה. קישורים לאפליקציה ל-Android משתמשים ב-Digital Asset Links API כדי ליצור אמון בכך שהאפליקציה שלכם אושרה על ידי האתר לפתוח קישורים באופן אוטומטי לדומיין הזה. אם המערכת תאמת שהכתובות בבעלותכם, היא תפנה אוטומטית את כוונת החיפוש של כתובות ה-URL האלה לאפליקציה שלכם.

כדי לאמת שהאפליקציה וכתובות ה-URL של האתר בבעלותכם:

1. מוסיפים מסנני Intent שמכילים את המאפיין autoVerify. המאפיין הזה מאותת למערכת שהיא צריכה לאמת אם האפליקציה שייכת לדומיינים של כתובות ה-URL שמשמשים במסנני הכוונה.

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

2. מגדירים את השיוך בין האתר שלכם למסנני הכוונה על ידי אירוח קובץ JSON של Digital Asset Links במיקום הבא:

   https://domain.name/.well-known/assetlinks.json

מידע נוסף זמין במקורות המידע הבאים:

• תמיכה בכתובות URL ובאינדקס של אפליקציות ב-Android Studio
• יצירת רשימת דפי חשבון

הוספת מסנני Intent לאימות קישורים לאפליקציות

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

<!-- Make sure you explicitly set android:autoVerify to "true". -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <!-- If a user clicks on a shared link that uses the "http" scheme, your
         app should be able to delegate that traffic to "https". -->
    <!-- Do not include other schemes. -->
    <data android:scheme="http" />
    <data android:scheme="https" />

    <!-- Include one or more domains that should be verified. -->
    <data android:host="..." />
</intent-filter>

אפשר לכלול את autoVerify רק בהצהרה אחת של <intent-filter> לכל מארח, גם אם המארח הזה משמש בהצהרות אחרות ללא סימון. עם זאת, מומלץ להוסיף את autoVerify לכל רכיב <intent-filter> כדי לשמור על עקביות. כך גם תוכלו לוודא שאחרי שתסירו רכיבים מקובץ המניפסט או תבצעו להם רפרסוקציה, האפליקציה תישאר משויכת לכל הדומיינים שעדיין מוגדרים בה.

תהליך האימות של הדומיין מחייב חיבור לאינטרנט, והוא עשוי להימשך זמן מה. כדי לשפר את היעילות של התהליך, המערכת מאמתת דומיין של אפליקציה שמטרגטת ל-Android 12 ואילך רק אם הדומיין נמצא בתוך רכיב <intent-filter> שמכיל את הפורמט המדויק שצוין בקטע הקוד הקודם. לדוגמה, סכמות שאינן 'http' ו-'https', כמו <data android:scheme="custom" />, ימנעו מ-<intent-filter> להפעיל את אימות הדומיין.

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

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

המערכת צריכה להיות מסוגלת לאמת את המארח שצוין ברכיבי הנתונים של מסנני הכוונה לכתובות URL באפליקציה, בהתאם לקובצי Digital Asset Links שמתארחים בדומיינים הרלוונטיים באינטרנט במסנן הכוונה הזה. אם האימות נכשל, המערכת תעבור להתנהגות רגילה כברירת מחדל כדי לטפל בכוונה, כפי שמתואר בקטע יצירת קישורי עומק לתוכן של אפליקציות. עם זאת, עדיין אפשר לאמת את האפליקציה כמתן שירות כברירת מחדל לכל אחד מהדפוסים של כתובות ה-URL שהוגדרו במסנני הכוונה האחרים של האפליקציה.

הערה: ב-Android 11 (רמת API 30) ובגרסאות ישנות יותר, המערכת לא מאמתת את האפליקציה כמתן שירות ברירת המחדל, אלא אם היא מוצאת קובץ Digital Asset Links תואם לכל המארחים שהגדרתם במניפסט.

לדוגמה, אפליקציה עם המסננים הבאים של כוונת השימוש תעבור את תהליך האימות רק עבור https://www.example.com אם נמצא קובץ assetlinks.json ב-https://www.example.com/.well-known/assetlinks.json אבל לא ב-https://www.example.net/.well-known/assetlinks.json:

<application>

  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name=”SecondActivity”>
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

הערה: כל הרכיבים מסוג <data> באותו מסנן כוונה ממוזגים יחד כדי להביא בחשבון את כל הווריאציות של המאפיינים המשולבים שלהם. לדוגמה, מסנן הכוונה הראשון שלמעלה כולל רכיב <data> שמצהיר רק על הסכימה HTTPS. אבל הוא משולב עם הרכיב השני של <data>, כך שמסנן הכוונה תומך גם ב-http://www.example.com וגם ב-https://www.example.com. לכן, צריך ליצור מסנני כוונה נפרדים אם רוצים להגדיר שילובים ספציפיים של דומיינים וסכימות URI.

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

פרוטוקול Digital Asset Links מתייחס לדומיינים משניים במסנני הכוונה כמארחים נפרדים וייחודיים. לכן, אם במסנן הכוונה מפורטים כמה מארחים עם תתי-דומיינים שונים, צריך לפרסם assetlinks.json תקין בכל דומיין. לדוגמה, מסנן ה-Intent הבא כולל את www.example.com ואת mobile.example.com כמארחים של כתובות URL של כוונות קבילות. לכן, צריך לפרסם assetlinks.json תקף גם ב-https://www.example.com/.well-known/assetlinks.json וגם ב-https://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

לחלופין, אם מגדירים את שם המארח באמצעות תו כללי לחיפוש (כמו *.example.com), צריך לפרסם את קובץ assetlinks.json בשם המארח ברמה הבסיסית (example.com). לדוגמה, אפליקציה עם מסנן הכוונה הבא תעבור את האימות לכל שם משנה של example.com (כמו foo.example.com) כל עוד קובץ assetlinks.json יפורסם ב-https://example.com/.well-known/assetlinks.json:

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

איך בודקים אם יש כמה אפליקציות שמשויכות לאותו דומיין

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

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

הערה: מומלץ לאחסן את הנתיב התואם כדי שהמשתמש לא יצטרך לבחור מחדש אם יהיה כוונה דומה באתר מאוחר יותר.

הצהרת שיוכים לאתרים

צריך לפרסם באתר קובץ JSON עם Digital Asset Links כדי לציין את אפליקציות Android המשויכות לאתר ולאמת את כוונת השימוש (intent) של כתובות ה-URL של האפליקציה. קובץ ה-JSON משתמש בשדות הבאים כדי לזהות אפליקציות משויכות:

• package_name: מזהה האפליקציה שמוצהר בקובץ build.gradle של האפליקציה.
• sha256_cert_fingerprints: טביעות האצבע מסוג SHA256 של אישור החתימה של האפליקציה. אפשר להשתמש בפקודה הבאה כדי ליצור את טביעת האצבע באמצעות ה-keytool של Java:

  keytool -list -v -keystore my-release-key.keystore
  

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

  אם אתם משתמשים בחתימה על אפליקציות ב-Play באפליקציה שלכם, בדרך כלל טביעת האצבע של האישור שנוצרת על ידי הפעלת keytool באופן מקומי לא תואמת לטביעת האצבע במכשירים של המשתמשים. אתם יכולים לבדוק אם אתם משתמשים ב-Play App Signing לאפליקציה שלכם בחשבון הפיתוח ב-Play Console בקטע Release > Setup > App signing. אם כן, תוכלו למצוא גם את קטע ה-JSON הנכון של Digital Asset Links לאפליקציה שלכם באותו דף.

קובץ assetlinks.json לדוגמה מעניק לאפליקציה com.example ל-Android את הרשאת פתיחת הקישור:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

שיוך אתר למספר אפליקציות

אתר יכול להצהיר על שיוך למספר אפליקציות באותו קובץ assetlinks.json. רשימת הקבצים הבאה מציגה דוגמה לקובץ הצהרה שמצהיר על שיוך לשתי אפליקציות בנפרד, ונמצא ב-https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

אפליקציות שונות יכולות לטפל בקישורים למקורות שונים באותו מארח אינטרנט. לדוגמה, אפליקציה אחת עשויה להצהיר על מסנן Intent עבור https://example.com/articles, ואפליקציה אחרת עשויה להצהיר על מסנן Intent עבור https://example.com/videos.

הערה: יכול להיות שאותן אישורים או אישורים שונים ייחתמו על כמה אפליקציות שמשויכות לדומיין.

שיוך של כמה אתרים לאפליקציה אחת

כמה אתרים יכולים להצהיר על שיוך לאותה אפליקציה בקבצים assetlinks.json המתאימים שלהם. הרשימות הבאות של הקבצים מציגות דוגמה להצהרה על השיוך של example.com ו-example.net אל app1. ברשימה הראשונה מוצג השיוך של example.com אל app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

ברשימה הבאה מוצגת השיוך של example.net אל app1. ההבדל הוא רק במיקום שבו הקבצים האלה מתארחים (.com ו-.net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

פרסום קובץ האימות בפורמט JSON

צריך לפרסם את קובץ האימות בפורמט JSON במיקום הבא:

https://domain.name/.well-known/assetlinks.json

חשוב לוודא את הפרטים הבאים:

• הקובץ assetlinks.json מוצג עם סוג התוכן application/json.
• צריכה להיות גישה לקובץ assetlinks.json דרך חיבור HTTPS, ללא קשר לכך שמסנני ה-Intent של האפליקציה מגדירים את HTTPS כסכימת הנתונים.
• צריכה להיות גישה לקובץ assetlinks.json ללא הפניות לכתובת אחרת (ללא הפניות מסוג 301 או 302).
• אם הקישורים באפליקציה תומכים במספר דומיינים מארחים, צריך לפרסם את הקובץ assetlinks.json בכל דומיין. תמיכה בקישור אפליקציות למספר מארחים
• אל תפרסמתם את האפליקציה עם כתובות URL של פיתוח/בדיקה בקובץ המניפסט, שעשויות להיות לא נגישות לציבור (למשל כתובות שאפשר לגשת אליהן רק באמצעות VPN). במקרים כאלה, אפשר להגדיר וריאנטים של build כדי ליצור קובץ מניפסט שונה לגרסאות build של הפיתוח.

אימות של קישורים לאפליקציות ל-Android

כשהערך android:autoVerify="true" מופיע באחד לפחות מסנני הכוונה של האפליקציה, התקנת האפליקציה במכשיר עם Android 6.0 (רמת API ‏23) ואילך גורמת למערכת לאמת באופן אוטומטי את המארחים המשויכים לכתובות ה-URL בסנני הכוונה של האפליקציה. ב-Android מגרסה 12 ואילך, אפשר גם להפעיל את תהליך האימות באופן ידני כדי לבדוק את הלוגיקה של האימות.

אימות אוטומטי

האימות האוטומטי של המערכת כולל את הפעולות הבאות:

1. המערכת בודקת את כל מסנני הכוונה שכוללים את אחד מהפרטים הבאים:
   • פעולה: android.intent.action.VIEW
   • קטגוריות: android.intent.category.BROWSABLE ו-android.intent.category.DEFAULT
   • סכמת נתונים: http או https
2. לכל שם מארח ייחודי שנמצא במסנני הכוונה שלמעלה, מערכת Android שולחת שאילתות לאתרים המתאימים לגבי קובץ Digital Asset Links בכתובת https://hostname/.well-known/assetlinks.json.

הערה: ב-Android מגרסה 11 (רמה 30 של API) וגרסאות קודמות, המערכת מגדירה את האפליקציה כ-handler ברירת המחדל של תבניות ה-URL שצוינו רק אם היא מוצאת קובץ תואם של קישורי נכסים דיגיטליים לכל המארחים במניפסט.

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

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

אימות ידני

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

חיבור לאינטרנט

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

תמיכה בתהליך המעודכן לאימות דומיינים

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

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

adb shell am compat enable 175408749 PACKAGE_NAME

איפוס המצב של קישורי אפליקציות ל-Android במכשיר

לפני שמפעילים באופן ידני את אימות הדומיין במכשיר, צריך לאפס את המצב של Android App Links במכשיר הבדיקה. כדי לעשות זאת, מריצים את הפקודה הבאה בחלון מסוף:

adb shell pm set-app-links --package PACKAGE_NAME 0 all

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

הפעלת תהליך אימות הדומיין

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

adb shell pm verify-app-links --re-verify PACKAGE_NAME

הערה: לפני שבודקים את התוצאות של הפקודה הזו, צריך להמתין כמה דקות עד שסוכן האימות יסיים את הבקשות שקשורות לאימות הדומיין.

בדיקת תוצאות האימות

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

adb shell pm get-app-links PACKAGE_NAME

הפלט של הפקודה אמור להיראות כך:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

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

ברשימה הבאה מפורטים ערכי ההחזרה האפשריים שיכולים להופיע בתוצאה של אימות הדומיין לדומיין נתון:

none

לא נרשם דבר לגבי הדומיין הזה. ממתינים עוד כמה דקות עד שסוכן האימות יסיים את הבקשות שקשורות לאימות הדומיין, ואז מפעילים שוב את תהליך אימות הדומיין.

verified

הדומיין אומת בהצלחה לאפליקציה שמצהירה עליו.

approved

הדומיין אושר בכפייה, בדרך כלל על ידי הפעלת פקודת מעטפת.

denied

הדומיין נדחה בכוח, בדרך כלל על ידי הפעלת פקודת מעטפת.

migrated

המערכת שמרה את התוצאה של תהליך קודם שנעשה בו שימוש באימות דומיינים מדור קודם.

restored

הדומיין אושר אחרי שהמשתמש ביצע שחזור נתונים. ההנחה היא שהדומיין אומת בעבר.

legacy_failure

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

system_configured

הדומיין אושר באופן אוטומטי על ידי הגדרות המכשיר.

קוד שגיאה 1024 ומעלה

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

מוודאים שיצרתם חיבור לרשת ומפעילים שוב את תהליך האימות של הדומיין.

בקשה מהמשתמש לשייך את האפליקציה לדומיין

דרך נוספת לאשר את האפליקציה לדומיין היא לבקש מהמשתמש לשייך את האפליקציה לדומיין הזה.

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

בודקים אם האפליקציה כבר אושרה לדומיין

לפני שמציגים למשתמש את ההודעה, צריך לבדוק אם האפליקציה היא הטיפול שמוגדר כברירת מחדל לדומיינים שאתם מגדירים ברכיבי <intent-filter>. אפשר לשלוח שאילתה לגבי מצב האישור באמצעות אחת מהשיטות הבאות:

• ה-API של DomainVerificationManager (בזמן הריצה).
• תוכנית בשורת הפקודה (במהלך בדיקה).

DomainVerificationManager

קטע הקוד הבא מדגים איך משתמשים ב-API של DomainVerificationManager:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the user
// has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user has
        // associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

תוכנית שורת פקודה

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

adb shell pm get-app-links --user cur PACKAGE_NAME

בדוגמה הבאה של הפלט, למרות שהאפליקציה נכשלה באימות לדומיין example.org, משתמש 0 אישר את האפליקציה באופן ידני בהגדרות המערכת, ואף חבילת אפליקציה אחרת לא אומתה לדומיין הזה.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

אפשר גם להשתמש בפקודות מעטפת כדי לדמות את התהליך שבו המשתמש בוחר איזו אפליקציה תהיה משויכת לדומיין נתון. הסבר מלא על הפקודות האלה זמין בפלט של adb shell pm.

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

לספק הקשר לבקשה

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

שליחת הבקשה

אחרי שהמשתמש מבין מה האפליקציה מבקשת ממנו לעשות, שולחים את הבקשה. כדי לעשות זאת, מפעילים כוונה שכוללת את פעולת הכוונה ACTION_APP_OPEN_BY_DEFAULT_SETTINGS ומחרוזת נתונים שתואמת ל-package:com.example.pkg באפליקציית היעד, כפי שמתואר בקטע הקוד הבא:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

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

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

איור 1. מסך הגדרות המערכת שבו המשתמשים יכולים לבחור אילו קישורים ייפתחו באפליקציה כברירת מחדל.

איור 2. תיבת דו-שיח שבה המשתמשים יכולים לבחור דומיינים נוספים שרוצים לשייך לאפליקציה.

דומיינים פתוחים באפליקציה שלא ניתן לאמת באפליקציה

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

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

בדיקת קישורים לאפליקציות

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

כדי לבדוק קובץ הצהרות קיים, אפשר להשתמש בכלי Statement List Generator and Tester.

מאשרים את רשימת המארחים שרוצים לאמת

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

• מאפיין android:scheme עם ערך http או https
• מאפיין android:host עם תבנית של כתובת URL של דומיין
• רכיב הפעולה android.intent.action.VIEW
• רכיב קטגוריה מסוג android.intent.category.BROWSABLE

אפשר להשתמש ברשימה הזו כדי לבדוק שקובץ JSON של Digital Asset Links מסופק בכל מארח ובכל תת-דומיין.

אימות הקבצים של Digital Asset Links

בכל אתר, משתמשים ב-Digital Asset Links API כדי לוודא שקובץ ה-JSON של Digital Asset Links מתארח ומוגדר בצורה תקינה:

https://digitalassetlinks.googleapis.com/v1/statements:list?
   source.web.site=https://domain.name:optional_port&
   relation=delegate_permission/common.handle_all_urls

בדיקת כללי המדיניות בנושא קישורים

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

adb shell dumpsys package domain-preferred-apps

אפשר גם לבצע את הפעולות הבאות:

adb shell dumpsys package d

הערה: חשוב להמתין לפחות 20 שניות אחרי התקנת האפליקציה כדי לאפשר למערכת להשלים את תהליך האימות.

הפקודה מחזירה רשימה של כל משתמש או פרופיל שהוגדרו במכשיר, שמוקדמת בכותרת בפורמט הבא:

App linkages for user 0:

אחרי הכותרת הזו, הפלט כולל את ההגדרות לטיפול בקישורים של המשתמש הזה בפורמט הבא:

Package: com.android.vending
Domains: play.google.com market.android.com
Status: always : 200000002

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

• Package – מזהה אפליקציה לפי שם החבילה שלה, כפי שמוצהר במניפסט שלה.
• Domains – הצגת הרשימה המלאה של המארחים שהאפליקציה מטפלת בקישורים לאתרים שלהם, באמצעות רווחים ריקים כמפרידי מחרוזות.
• Status – מופיעה ההגדרה הנוכחית לטיפול בקישורים באפליקציה הזו. לאפליקציה שעברה אימות, שמניפסט שלה מכיל את הערך android:autoVerify="true", יופיע הסטטוס always. המספר ההקסאדצימלי שמופיע אחרי הסטטוס הזה קשור לרשומות של מערכת Android לגבי העדפות הקישור של המשתמש לאפליקציות. הערך הזה לא מציין אם האימות הצליח.

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

דוגמה לבדיקה

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

<application>

    <activity android:name=”MainActivity”>
        <intent-filter android:autoVerify="true">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:scheme="https" />
            <data android:host="www.example.com" />
            <data android:host="mobile.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="www.example2.com" />
        </intent-filter>
    </activity>

    <activity android:name=”SecondActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="account.example.com" />
        </intent-filter>
    </activity>

      <activity android:name=”ThirdActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="https" />
            <data android:host="map.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="market" />
            <data android:host="example.com" />
        </intent-filter>
      </activity>

</application>

רשימת המארחים שהפלטפורמה תנסה לאמת מהמניפסט שלמעלה היא:

www.example.com
mobile.example.com
www.example2.com
account.example.com

רשימת המארחים שהפלטפורמה לא תנסה לאמת מהמניפסט שלמעלה היא:

map.example.com (it does not have android.intent.category.BROWSABLE)
market://example.com (it does not have either an "http" or "https" scheme)

מידע נוסף על רשימות הצהרות זמין במאמר יצירת רשימת הצהרות.

תיקון שגיאות נפוצות בהטמעה

אם אתם לא מצליחים לאמת את הקישורים לאפליקציות ל-Android, כדאי לבדוק אם קיימות אחת מהשגיאות הנפוצות הבאות. בקטע הזה נעשה שימוש ב-example.com בתור placeholder של שם הדומיין. כשמבצעים את הבדיקות האלה, צריך להחליף את example.com בשם הדומיין בפועל של השרת.

הגדרה שגויה של מסנן כוונה

בודקים אם כלולה רכיב <intent-filter> שכתובת ה-URL שלו לא בבעלות האפליקציה.

הגדרת שרת שגויה

בודקים את הגדרת ה-JSON של השרת ומוודאים שערך ה-SHA נכון.

בנוסף, צריך לבדוק ש-example.com. (עם הנקודה בסוף) מציג את אותו תוכן כמו example.com.

הפניות אוטומטיות בצד השרת

אם תגדירו הפניה אוטומטית, למשל:

• http://example.com עד https://example.com
• example.com עד www.example.com

ההתנהגות הזו מגינה על האבטחה של האפליקציה.

חוסן השרת

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

קישורים שלא ניתן לאמת

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

חתימת שגויה בקובץ assetlinks.json

מוודאים שהחתימה נכונה ותואמת לחתימה ששימשה לחתימה על האפליקציה. אלה כמה מהטעויות הנפוצות:

• חתימה על האפליקציה באמצעות אישור לניפוי באגים, ורק חתימה על הגרסה היציבה נמצאת ב-assetlinks.json.
• חתימה באותיות קטנות ב-assetlinks.json. החתימה צריכה להיות באותיות רישיות.
• אם אתם משתמשים בחתימת אפליקציה ב-Play, חשוב לוודא שאתם משתמשים בחתימה שבה Google משתמשת כדי לחתום על כל אחת מהגרסאות שלכם. כדי לאמת את הפרטים האלה, כולל קטע JSON מלא, פועלים לפי ההוראות להצהרה על שיוך לאתרים.