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

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

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

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

1. המערכת בודקת את כל מסנני ה-Intent שכוללים את אחד מהרכיבים הבאים:
   • פעולה: android.intent.action.VIEW
   • קטגוריות: android.intent.category.BROWSABLE ו-android.intent.category.DEFAULT
   • סכימת נתונים: http או https
2. לכל שם מארח ייחודי שנמצא במסנני ה-Intent, מערכת 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 ומעלה

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

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

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

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

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

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

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

DomainVerificationManager

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

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.

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

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

שליחת הבקשה

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

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

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

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

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

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