陳述式清單語法

聲明清單是經過 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> 必須完整，且使用 HTTP 的通訊埠 80 或 HTTPS 的通訊埠 443 時必須省略 <port>。網站目標只能是根網域，無法限制為特定子目錄，這個根網域下的所有目錄都會相符。子網域不應視為相符項目：也就是說，如果聲明檔案託管於 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

  這項陳述式適用的應用程式完整套件名稱。範例： com.google.android.apps.maps

  sha256_cert_fingerprints

  這個陳述式適用的應用程式憑證大寫 SHA265 指紋。您可以使用 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 管理中心的開發人員帳戶，然後前往 Release > Setup > App Integrity。如果應用程式使用這項功能，您會在同一頁面找到應用程式的正確 Digital Asset Links JSON 程式碼片段。

relation_extensions (選用)

您可以在陳述式中加入選用的 relation_extensions 欄位，進一步提供想授予的權限和關聯資訊。這個欄位應為物件，其中每個鍵都是關係字串，值則是包含該關係擴充功能的物件。要求這些陳述的用戶端必須更新，才能遵守這些欄位。

舉例來說，delegate_permission/common.handle_all_urls 關係的 relation_extensions 可能如下所示：

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

在要求中設定 return_relation_extensions=true 參數後，DAL API 即可在 API 呼叫中傳回 relation_extensions。

陳述清單範例

以下是網站聲明清單範例，其中包含網站和應用程式的聲明：http://example.digitalassetlinks.org/.well-known/assetlinks.json

可擴充至數十個以上的陳述式

在某些情況下，主體可能想針對不同目標發布許多不同聲明，或是需要由不同主體對同一組目標發布聲明。舉例來說，網站可能在許多不同的國家/地區頂層網域上提供服務，而這些網域可能都想聲明與同一個行動應用程式的關係。

在這些情況下，include 陳述式會很有幫助。 使用這項機制，您可以從許多不同的主體設定指標到一個中央位置，該位置會定義所有主體的陳述式。

注意：完整陳述式清單樹狀結構最多只能有 10 個 include 陳述式。也就是說，樹狀結構中的檔案數量上限為：(10 個內含陳述式檔案) + (根陳述式檔案) = 總共 11 個。

舉例來說，您可能會決定中央位置應為 `https://example.com/includedstatements.json`。這個檔案可設定為包含與上述範例相同的內容。

如要設定從網站到 include 檔案的指標，請將 `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>

更多資訊

如要進一步瞭解陳述式清單格式和基本概念，請參閱規格文件。