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

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

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

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

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

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

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

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

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

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

• התאמת נתיב
  • מקש: "/"
  • ערך: מחרוזת אחת, ביטוי תואם לנתיב כתובת ה-URL
• התאמת קטעים
  • מקש: "#"
  • ערך: מחרוזת אחת, ביטוי תואם לפרגמנט ה-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}
]

אם לא נמצאו התאמות ברשימת הרכיבים המוצהרים, כתובת ה-URL לא תפתח את האפליקציה. בדוגמה הבאה, אף אחד מהנתיבים לא תואם ל-"/path3", ולכן המכשיר יתייחס לנתיב הזה כמוחרג.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

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

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

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

מכשירי 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
• כלים למפתחים בנושא קישורים לאפליקציות