Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

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