Digital Asset Links

Definition

Digital Asset Links is an open protocol for publishing verifiable statements in which one digital asset, such as a website, grants a specific permission to another, such as a mobile app identified by its package name and signing certificate fingerprint.

It is routinely confused with the file that implements it. `assetlinks.json` is one serialisation of one statement type; the protocol is broader, and it is what Android App Links verification, Chrome credential sharing, Trusted Web Activities and Instant Apps all sit on top of. Understanding the protocol is what lets you debug the cases where the file looks correct and the permission still is not granted.

The statement, as the protocol defines it

A statement has exactly three parts: the source asset making the claim, the relation being granted, and the target asset receiving it. Everything else is transport.

{
  "source": {
    "web": { "site": "https://shop.example.com" }
  },
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "androidApp": {
      "package_name": "com.example.shop",
      "certificate": {
        "sha256_fingerprint":
          "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"
      }
    }
  }
}

The file at /.well-known/assetlinks.json is an array of these objects with the source omitted, because the source is implied by where the file is hosted. That omission is the whole reason the protocol and the file get conflated — the file only ever expresses statements *from* the domain serving it.

Statement lists and the include mechanism

A statement list can delegate to another location rather than enumerating statements inline, which is how large organisations centralise the file across many hostnames.

[{
  "include": "https://central.example.com/.well-known/statements.json"
}]

• The include target must be served over HTTPS with a valid certificate.
• Statements in the included list still apply to the *including* host, not to the host serving them.
• Nesting depth is limited, and a broken include invalidates the whole list rather than degrading to the inline statements.
• It does not remove the need for the file on each hostname — it only removes the need to maintain the statement content in each place.

Verifying a statement without a device

Google runs a public API that evaluates the protocol the same way Android does, which is the fastest way to distinguish "my file is wrong" from "my file is right and the device has not re-verified".

curl -s 'https://digitalassetlinks.googleapis.com/v1/statements:list?\
source.web.site=https://shop.example.com&\
relation=delegate_permission/common.handle_all_urls' | jq

# A useful response contains "statements" and an empty "debugString".
# Errors you will actually see:
#   "Unable to fetch" ....... 404, auth wall, or a redirect
#   "Content-Type" .......... served as text/html instead of application/json
#   "malformed" ............. trailing comma, BOM, or a fingerprint with spaces

# And the device-side truth, which the API cannot tell you:
adb shell pm get-app-links com.example.shop

The overwhelmingly common cause of a valid-looking file that does not verify is the SHA-256 fingerprint: Play App Signing re-signs your app with a key you never handled, so the fingerprint from your local keystore is the wrong one to publish.