Creating a Statement List

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.