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

כדי לתמוך בקישורי עומק לאפליקציות, צריך ליצור קובץ 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}
]

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

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

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