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

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

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

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

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

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

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

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

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

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

כל תיבת סימון מייצגת דומיין שאפשר להוסיף. הכפתורים בתיבת הדו-שיח הם 'ביטול' ו'הוספה'.

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

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

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

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

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

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

אימות ידני

מתחברים לאינטרנט

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

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

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

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

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

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

DomainVerificationManager

Kotlin

Java

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

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

שליחת הבקשה

Kotlin

Java

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

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