התחביר של רשימת הדוחות

רשימת ההצהרות היא קובץ או קטע בקידוד JSON במיקום ידוע.

מיקום רשימת ההצהרות

במאמר בנושא יצירת רשימת הצהרות מוסבר איפה צריך לשמור את הרשימה הזו.

תחביר

רשימת ההצהרות או קטע הקוד מורכבים ממערך JSON של הצהרה אחת או יותר של אתר או אפליקציה כאובייקטים בפורמט JSON. אפשר לכתוב את ההצהרות בכל סדר. זהו התחביר הכללי:

[
  {
    "relation": ["relation_string"],
    "target": {target_object}
  } , ...
]

relation

מערך של מחרוזת אחת או יותר שמתארות את הקשר שמוצהר לגבי היעד. כאן מפורטת רשימת המחרוזות של קשרי הגומלין המוגדרים. דוגמה: delegate_permission/common.handle_all_urls

יעד

‫

הנכס שאליו מתייחסת ההצהרה הזו. סוגי היעדים הזמינים:

• יעד אתר

  "target": {
    "namespace": "web",
    "site": "site_root_url"
  }

  מרחב שמות

  חייב להיות web לאתרים.

  אתר

  מזהה ה-URI של האתר שהוא היעד של ההצהרה, בפורמט http[s]://<hostname>[:<port>], כאשר <hostname> הוא שם דומיין מלא, וצריך להשמיט את <port> כשמשתמשים ביציאה 80 ל-HTTP או ביציאה 443 ל-HTTPS. יעד אתר יכול להיות רק דומיין בסיסי (root). אי אפשר להגביל אותו לספרייה משנה ספציפית. כל הספריות שמתחת לדומיין הבסיסי יתאימו. תת-דומיינים לא נחשבים כתואמים: כלומר, אם קובץ ההצהרה מתארח בכתובת www.example.com, הכתובת www.puppies.example.com לא נחשבת כתואמת. במסמכי התיעוד בנושא טירגוט אפשר למצוא כללים ודוגמאות בנושא התאמה של יעדים באתר. דוגמה: http://www.example.com

• אפליקציית Android לטירגוט

  "target": {
    "namespace": "android_app",
    "package_name": "fully_qualified_package_name",
    "sha256_cert_fingerprints": ["cert_fingerprint"]
  }

  מרחב שמות

  חייב להיות android_app לאפליקציות ל-Android.

  package_name

  ‫

  The fully-qualified package name of the app that this statement applies to. דוגמה: com.google.android.apps.maps

  sha256_cert_fingerprints

  טביעת האצבע באותיות רישיות מסוג SHA256 של האישור של האפליקציה שאליה מתייחסת ההצהרה הזו. אפשר לחשב את זה באמצעות openssl או Java keytool כמו שמוצג כאן:

  • openssl x509 -in $CERTFILE -noout -fingerprint -sha256
  • keytool -printcert -file $CERTFILE | grep SHA256

  לדוגמה: ["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"].

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

relation_extensions (אופציונלי)

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

לדוגמה, relation_extensions עבור הקשר delegate_permission/common.handle_all_urls יכול להיראות כך:

  {
    "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": {...}
    }
  }
  

ה-API של DAL תומך בהחזרת relation_extensions בקריאות ל-API, כשהפרמטר return_relation_extensions=true מוגדר בבקשה.

רשימת הצהרות לדוגמה

הנה דוגמה לרשימת הצהרות באתר שמכילה הצהרות לגבי אתרים ואפליקציות: http://example.digitalassetlinks.org/.well-known/assetlinks.json

התאמה לשימוש בעשרות דפי חשבון או יותר

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

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

לדוגמה, יכול להיות שתחליטו שהמיקום המרכזי יהיה `https://example.com/includedstatements.json`. אפשר להגדיר את הקובץ הזה כך שיכיל את אותו תוכן כמו בדוגמאות שלמעלה.

כדי להגדיר הצבעה מאתר לקובץ הכלול, צריך לשנות את `https://example.com/.well-known/assetlinks.json` ל:

[{
  "include": "https://example.com/includedstatements.json"
}]

כדי להגדיר מצביע מאפליקציה ל-Android לקובץ include, משנים את `res/values/strings.xml` כך:

<resources>
  ...
  <string name="asset_statements">
    [{
      \"include\": \"https://example.com/includedstatements.json\"
    }]
  </string>
</resources>

מידע נוסף

הסבר מפורט יותר על הפורמט של רשימת ההצהרות ועל המושגים שמאחורי הפורמט הזה מופיע במסמך המפרט.