Introduction
Digital Asset Links is Google’s way for the owner of one digital asset (a website, an Android app) to make public statements about its relationship with another. The statements are kept
in a JSON statement list. A website’s list is the file assetlinks.json at scheme://domain/.well-known/assetlinks.json. Google says: “This is the official name and location for a statement
list on a site; statement lists in any other location, or with any other name, are not valid for this site.” It must be served with HTTP 200 and Content-Type: application/json, and “it cannot be a redirect (that is,
301 or 302 response codes are not followed)”. The commonest use is Android App Links: the file lists the apps allowed to open the site’s links. An Android app keeps its own list as a JSON snippet in strings.xml.
Structure
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": ["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"]
}
},
{ "include": "https://example.com/includedstatements.json" }
]
| Part | Rule |
|---|---|
| the list | A JSON array of one or more statements, in any order. |
relation | An array of one or more strings, each “kind/detail”. The only kind is delegate_permission, a permission rather than a requirement. The detail matches [a-z0-9_.]+. The predefined detail is
common.handle_all_urls (the ability to handle all URLs the source can handle); Google’s pages also show common.share_location in an example. |
target, namespace web | site: http[s]://<fully qualified host>[:port], with the port omitted when it is the default for the scheme. A website target is a root domain only; all paths under it match, subdomains do not. |
target, namespace android_app | package_name: the fully qualified package name. sha256_cert_fingerprints: the SHA-256 fingerprints of the signing certificate, upper-case hexadecimal pairs separated by colons.
Several fingerprints are shorthand for several targets. Google warns that with Play App Signing the fingerprint from your own key is usually not the one on users’ devices. |
relation_extensions | Optional. An object whose keys are relation strings and whose values hold extensions for that relation. |
include | A statement that points to another file of statements. It must be served over SSL, only an HTTP 200 counts, and redirects are not followed. “A maximum of 10 include statements are allowed in a complete statement list tree.” |
The specification text (details.md in Google’s digitalassetlinks repository) also names an ios_app namespace with an appid; the Google pages read for this site do not.
In the explorer
A file named assetlinks.json opens here when it is a non-empty array whose every element is an include statement or a statement with a relation array and a target object with a
namespace. Any other file with that name opens as JSON, as before. The tree names each member; the Statements tab lists them. A problem is a rule above that is broken: a site with a path or the default port written out or a host that is not
fully qualified, a package name that is not dotted, a fingerprint that is not 32 upper-case colon-separated hexadecimal pairs, a relation that is not “kind/detail”, a kind other than delegate_permission, a detail with characters outside
[a-z0-9_.]+, an include that is not https, more than ten includes. Nothing is fetched: the file is not compared with the app’s real certificate or the address it was served from.
Not described
Known, not yet covered
- Reference: the Digital Asset Links API (the lookup service), the Android side (the manifest’s
asset_statementsresource) and the list of relations other products define are not described. - Viewer: the file is not matched against an entity (the target-matching rules for websites and apps are described by Google but need a real URL or app); the include tree is not followed.
- Viewer: fingerprints and package names are checked for shape only; a SHA-256 value is not compared with a certificate.
Unknown
- Reference: a size limit for the file: the pages read give none.
Links
Reference
- Statement List Syntax – Google Digital Asset Links
- Creating a statement list – where it lives and how a target is matched
- Getting started – the Android App Links example
- Asset Links specification – the data types and relations