Creating a Statement List

  • Statements are stored in a JSON-encoded list called a statement list, located at a well-known location associated with a principal (website or app).

  • Websites host their statement lists in a text file at scheme://domain/.well-known/assetlinks.json, requiring an HTTP 200 response and Content-Type: application/json.

  • Android apps embed their statement lists as a JSON snippet within the strings.xml file and reference it in the AndroidManifest.xml.

  • Matching a statement target involves comparing the statement's defined target against a real-world entity, with specific matching rules for websites and apps.

Statements are hosted in a JSON-encoded statement list in a well-known location on a principal, as defined by the Asset Links Specification. A statement list contains one or more statements, and a principal can have only one statement list.

Statement list syntax

See the statement list syntax.

Statement list location

The statement list is hosted in a well known location that depends on the type of principal (the website or app making the statements).

Website statement lists

On a website, a statement list is a text file located at the following address:

scheme://domain/.well-known/assetlinks.json

Note the dot in the .well-known folder name.

Any response from the server besides HTTP 200 is treated as an error, and will result in an empty statement list. For HTTPS, any connection without a certificate chain that can be verified with the trusted root list will also result in an empty statement list.

Example

Here is an example statement list on a website: http://example.digitalassetlinks.org/.well-known/assetlinks.json

Android app statement lists

In an Android app, the statement list is a JSON snippet with the same syntax as a website statement file, but it is embedded in the strings.xml file, and referenced in the manifest as shown next.

In AndroidManifest.xml:

<manifest>
  <application>
    ...
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
    ...
  </application>
</manifest>

In res/values/strings.xml:

<resources>
  ...
  <string name="asset_statements">
    ... statement list ...
  </string>
</resources>

Example

Here is an example res/values/strings.xml snippet for an Android app that supports location sharing with the app (an Android feature not currently supported):

<resources>
    ...
    <string name="asset_statements">
      [{
        \"relation\": [\"delegate_permission/common.share_location\"],
        \"target\": {
          \"namespace\": \"web\",
          \"site\": \"https://example.com\"
        }
      }]
    </string>
</resources>

Matching a target

Every statement is about a target. When you consume a statement, you must match the target in a statement against some entity in reality. If the statement target matches the entity, the statement applies. Here are the rules for determining if a target matches a given entity:

Website targets

For a website, the site scheme, host, and port must match exactly. Default ports for HTTP and HTTPS (80 and 443 respectively) are assumed implicitly; if a statement target describes http://www.example.com:80, then the website http://www.example.com is considered a match.

Example

Given the following statement target

"target": {
  "namespace": "web",
  "site": "https://www.google.com"
}

The following URIs WILL match:

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

The following URLs will NOT match:

  • http://www.google.com/ (Wrong scheme)
  • https://google.com/ (Host name does not match)
  • https://www.google.com:444/ (Port does not match)

App targets

For an app, the certificate hash and package name of the target must exactly match the application.