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

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

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

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

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

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

כדאי לעיין במדריכים הקשורים הבאים: