Statement List Syntax

A statement list is a JSON-encoded file or snippet in a well-known location.

Location of statement list

See Creating a statement list to learn where this list should be stored.

Syntax

The statement list or snippet consists of a JSON array of one or more website or app statements as JSON objects. These statements can be in any order. Here is the general syntax:

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

relation

An array of one or more strings that describe the relation being declared about the target. See the list of defined relation strings. Example: delegate_permission/common.handle_all_urls

target

The target asset to whom this statement applies. Available target types:

• Website target

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

  namespace

  Must be web for websites.

  site

  URI of the site that is the target of the statement, in the format http[s]://<hostname>[:<port>], where <hostname> is fully-qualified, and <port> must be omitted when using port 80 for HTTP, or port 443 for HTTPS. A website target can only be a root domain; you cannot limit to a specific subdirectory; all directories under this root will match. Subdomains should not be considered to match: that is, if the statement file is hosted on www.example.com, then www.puppies.example.com should not be considered a match. For rules and examples about website target matching, see the targets documentation. Example: http://www.example.com

• Android app target

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

  namespace

  Must be android_app for Android apps.

  package_name

  The fully-qualified package name of the app that this statement applies to. Example: com.google.android.apps.maps

  sha256_cert_fingerprints

  The uppercase SHA265 fingerprint of the certificate for the app that this statement applies to. You can compute this using openssl or Java keytool as shown here:

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

  Example: ["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"].

  If you're using Play App Signing for your app, then the certificate fingerprint produced by running keytool or openssl locally usually doesn't match the one on users' devices. You can verify whether you're using Play App Signing for your app in your Play Console developer account under Release > Setup > App Integrity; if you do, then you'll also find the correct Digital Asset Links JSON snippet for your app on the same page.

relation_extensions (optional)

You can add an optional relation_extensions field to a statement to provide more information on the permissions and associations you want to grant. This field should be an object where each key is a relation string, and the value is an object containing the extensions for that relation. Clients that request these statements need to be updated to respect these fields.

For example, relation_extensions for the delegate_permission/common.handle_all_urls relation may look like:

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

The DAL API supports returning relation_extensions in API calls when the return_relation_extensions=true parameter is set in the request.

Example statement list

Here is an example website statement list that contains statements about both websites and apps: http://example.digitalassetlinks.org/.well-known/assetlinks.json

Scaling to dozens of statements or more

In some cases, a principal might want to make many different statements about different targets, or there might be a need to issue statements from different principals to the same set of targets. For example, a website may be available on many different per-country Top Level Domains, and all of them may want to make a statement about the same mobile app.

For these situations, include statements can be helpful. Using this mechanism, you can set up pointers from many different principals to one central location, which defines statements for all of the principals.

For example, you might decide that the central location should be `https://example.com/includedstatements.json`. This file can be configured to contain the same content as in the examples above.

To set up a pointer from a web site to the include file, change `https://example.com/.well-known/assetlinks.json` to:

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

To set up a pointer from an Android app to the include file, change `res/values/strings.xml` to:

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

More Information

There is a more detailed explanation of the statement list format and the underlying concepts in our specification document.