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

כדי לתמוך בקישורי עומק לאפליקציות, צריך ליצור קובץ JSON של Digital Asset Links בשם assetlinks.json ולפרסם אותו במיקום מוכר באתר. בקובץ הזה מוצהר באופן פומבי אילו אפליקציות מורשות לטפל בקישורים בדומיין שלכם, ומכשירי Android יאחזרו את הקובץ הזה מהשרת שלכם כדי לאמת את קישורי העומק.

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

במדריך הזה מוסבר איך להכין קובץ assetlinks.json ולפרסם אותו באתר. אם אתם מעדיפים, אתם יכולים ליצור קובץ assetlinks.json באמצעות הכלי Play Deep Links או App Links Assistant ב-Android Studio. מידע נוסף זמין במאמר בנושא כלים למפתחים של קישורי אפליקציות.

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

כדי לציין את אפליקציות Android שמשויכות לאתר ולאמת את כוונות כתובות ה-URL של האפליקציה, צריך לפרסם באתר קובץ JSON עם Digital Asset Links. קובץ ה-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"]
  }
}]

הגדרת כללים דינמיים

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

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

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

נקודות חשובות לגבי הקוד

• קישורי עומק דינמיים לאפליקציה מוסיפים תוסף חדש של Digital Asset Links בשם dynamic_app_link_components, שבו מגדירים את הכללים הדינמיים.
• כללים דינמיים יכולים לכלול התאמות לדפוסים של נתיב, פרגמנט ופרמטרים של שאילתה.
• אפשר גם לסמן כל תבנית להתאמת מחרוזות כלא כלולה, כדי שכתובות URL תואמות לא יפתחו את האפליקציה.
• בדוגמה הזו מוצגים התאמות לנתיב ("/"), למקטע ("#") ולפרמטרים של שאילתה ("?"), וגם התאמות שמוחרגות ("exclude")
• אם יש שדות בקובץ שהפורמט שלהם שגוי או שהם ריקים, מערכת Android מבטלת את הכללים הדינמיים והמכשיר חוזר לכללים שהוגדרו באופן סטטי במניפסט של האפליקציה.

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

הצהרה על כללים דינמיים

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

• התאמת נתיבים
  • מקש: '/'
  • ערך: מחרוזת יחידה, ביטוי תואם לנתיב כתובת ה-URL
• התאמה של Fragment
  • מקש: '#'
  • ערך: מחרוזת יחידה, ביטוי תואם לפרגמנט של כתובת ה-URL
• התאמה של פרמטרים של שאילתה
  • מפתח: '?'
  • ערך: מילון להתאמה של צמדי מפתח/ערך בפרמטרים של שאילתות בכתובת ה-URL.
  • לדוגמה, המילון {"?", {"dl": "*", "in_app":"true"} יתאים למחרוזת השאילתה "?in_app=true&dl=abc".
  • הסדר של צמדי המפתח/ערך במילון לא צריך להיות זהה לסדר של הצמדים במחרוזת השאילתה. בנוסף, המילון לא צריך להתאים לכל צמדי המפתח/ערך במחרוזת השאילתה, אבל צריך למצוא התאמה לכל רשומה במילון.
  • לדוגמה, המילון יתאים גם למחרוזת השאילתה ?lang=en&in_app=true&tz=pst&dl=abc, אבל לא למחרוזת השאילתה ?lang=en&tz=pst&dl=abc
• לא נכלל
  • מפתח: exclude
  • ערך: ערך אופציונלי של true או false לכל כלל שמוגדר ב-dynamic_app_link_components (ראו דוגמה).

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

• התו '*' תואם לאפס תווים או יותר עד שמוצאים במחרוזת התואמת את התו שאחרי התו הכללי בתבנית
• ‫'?' תואם לכל תו בודד
• ‫'?*' מתאים לתו אחד או יותר

אין הגבלות אחרות על התווים בערכים.

שינוי סדר הכללים הדינמיים

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

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

dynamic_app_link_components: [
  {​"/": "*", exclude: true},
  {​"/": "/path1"}
]

עם זאת, בדוגמה הבאה, הכלל '/path1' מוצהר ראשון, ולכן הוא יוערך ראשון והאפליקציה תיפתח עבור כתובת URL שתואמת ל-'/path1'. הכלל השני, שמוציא מכלל אפשרות את כל כתובות ה-URL לפתיחת האפליקציה, ייבדק שני, אבל רק אם הכלל הראשון לא מתאים.

dynamic_app_link_components: [
  {​"/": "/path1"},
  {​"/": "*", exclude: true}
]

הגדרת היקף נכון לכללים הדינמיים

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

הכללים הדינמיים שמוצהרים בקובץ assetlinks.json יכולים לציין רק כללים למארחים שהצהרתם עליהם בקובץ AndroidManifest.xml של האפליקציה. הכללים הדינמיים לא יכולים להרחיב את היקף הכללים של כתובות ה-URL שמוצהרים באופן סטטי במניפסט של האפליקציה.

לכן מומלץ להשתמש בגישה הזו בכללים הדינמיים והסטטיים:

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

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

הצהרה על dynamic_app_link_components רק פעם אחת

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

• מחפשים כמה הצהרות לאותו אתר, לאותה אפליקציה ולאותו קשר, שמצהירות על אובייקט dynamic_app_link_components.
• מחפשים כמה אובייקטים מסוג dynamic_app_link_components שהוצהרו בהצהרה אחת

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

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

אם אתם כבר תומכים ב-App Links, אתם יכולים להוסיף תמיכה ב-Dynamic App Links ישירות לקובץ assetlinks.json הקיים. שדות הקשר לאימות הקישורים לאפליקציות נשארים ללא שינוי, ואפשר להוסיף את שדות התוסף החדשים של הקשר לכללים דינמיים בלי לבצע שינויים אחרים.

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

פרסום קובץ האימות בפורמט 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 לבדיקה בקובץ המניפסט, שאולי לא יהיו נגישות לציבור (למשל, כתובות URL שנגישות רק באמצעות VPN). פתרון עקיף במקרים כאלה הוא הגדרת וריאציות של build כדי ליצור קובץ מניפסט שונה לגרסאות build של פיתוח.

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

• יצירת רשימת הצהרות
• App Links Assistant ב-Android Studio
• כלים למפתחים בנושא קישורים לאפליקציות