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

אם התכונה 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. לכל שם מארח ייחודי שנמצא במסנני ה-Intent שלמעלה, מערכת Android שולחת שאילתה לאתרים המתאימים כדי למצוא את קובץ Digital Asset Links בכתובת https:///.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:

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.

כדאי לספק הקשר לבקשה

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

שליחת הבקשה

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

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

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

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

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

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

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

זמן האחזור של עדכון Digital Asset Links

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

  • ‫Android מגרסה 15 (רמת API‏ 35) ואילך: המערכת מאמתת מחדש את הדומיינים ברקע באופן תקופתי. יכול להיות שיחלפו עד שבעה ימים עד שהשינויים יחולו על כל מכשירי משתמשי הקצה, בגלל השמירה במטמון והאימות מחדש המתוזמן של המערכת.
  • ‫Android 14 (רמת API 34) וגרסאות קודמות: המערכת לא מבצעת אימות מחדש תקופתי ברקע. בדרך כלל, עדכונים בקובץ נקלטים רק כשהאפליקציה מותקנת או מתעדכנת.

עדכונים לגבי בדיקות

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