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

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

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

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

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

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

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

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

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

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

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

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

המערכת צריכה להיות מסוגלת לאמת את המארח שצוין ברכיבי הנתונים של מסנני ה-Intent של כתובת ה-URL של האפליקציה, מול קבצי Digital Asset Links שמתארחים בדומיינים הרלוונטיים באינטרנט במסנן ה-Intent הזה. אם האימות נכשל, המערכת חוזרת להתנהגות הרגילה שלה כדי לפתור את הכוונה, כפי שמתואר במאמר יצירת קישורי עומק לתוכן באפליקציה. עם זאת, עדיין אפשר לאמת את האפליקציה כרכיב handler שמוגדר כברירת מחדל לכל אחד מדפוסי כתובות ה-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 של Intent. לכן, צריך לפרסם 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>

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

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

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

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

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

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

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

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

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

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

[{
  "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"]
  }
}]

אפליקציות שונות יכולות לטפל בקישורים למשאבים שונים באותו מארח אתרים. לדוגמה, אפליקציה 1 יכולה להצהיר על מסנן Intent עבור https://example.com/articles, ואפליקציה 2 יכולה להצהיר על מסנן 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 מוגש עם content-type‏ application/json.
• צריכה להיות גישה לקובץ assetlinks.json דרך חיבור HTTPS, בלי קשר לשאלה אם מסנני ה-Intent של האפליקציה מצהירים שסכימת הנתונים היא HTTPS.
• צריך לוודא שאפשר לגשת לקובץ assetlinks.json ללא הפניות לכתובת אחרת (ללא הפניות מסוג 301 או 302).
• אם קישורי האפליקציה תומכים במספר דומיינים מארחים, צריך לפרסם את הקובץ assetlinks.json בכל דומיין. מידע נוסף על תמיכה בקישור אפליקציות למספר מארחים
• אל תפרסמו את האפליקציה עם כתובות URL של פיתוח או בדיקה בקובץ המניפסט, שאולי לא יהיו נגישות לציבור (למשל, כתובות 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.

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

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>. אפשר לשלוח שאילתה לגבי מצב האישור באחת מהשיטות הבאות:

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

DomainVerificationManager

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

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 }

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.

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

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

שליחת הבקשה

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

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)

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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

המערכת לא מאמתת אף קישור לאפליקציית Android עבור האפליקציה שלכם אם הגדרתם הפניה אוטומטית כמו זו:

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

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

חוסן השרת

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

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

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

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

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

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