The Complete Guide to assetlinks.json with Google Play App Signing

The Google Play App Signing Catch

Android App Links allow URLs to seamlessly open your Android application without displaying the 'Open with' system disambiguation dialog. The verification mechanism requires hosting a file at /.well-known/assetlinks.json containing the SHA-256 certificate fingerprint of your APK.

The most frequent reason Android App Links fail in production is a fingerprint mismatch caused by Google Play App Signing. When Play App Signing is enabled, developers sign their release bundle with an upload key, but Google Play strips that signature and re-signs the APK with a permanent app signing key before distributing it to end users.

If your assetlinks.json file contains the fingerprint from your local upload keystore, Android verification will fail on every consumer device downloaded from the Google Play Store.

Extracting the Authoritative SHA-256 Fingerprint

To locate the correct fingerprint that matches what your users actually receive, follow these steps:

1. Log in to the Google Play Console and select your application.

2. In the left navigation menu, expand 'Release' and click on 'App Integrity'.

3. Locate the 'App signing key certificate' tab (not the 'Upload key certificate').

4. Copy the hexadecimal string listed under 'SHA-256 certificate fingerprint'.

Hosting the Verified Assetlinks File

The association file must be hosted at /.well-known/assetlinks.json on your verified custom domain. It must return HTTP status 200, Content-Type: application/json, and be served without any HTTP redirect hops.

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.acme.app",
      "sha256_cert_fingerprints": [
        "14:6D:E9:7D:6D:3F:8A:77:47:3F:6A:A8:12:4F:2E:3A:4C:5D:6E:7F:8A:9B:0C:1D:2E:3F:4A:5B:6C:7D:8E:9F"
      ]
    }
  }
]

Verifying Domain Verification Status

On Android 12 and later, you can inspect the domain verification state directly via ADB shell:

adb shell pm get-app-links com.acme.app

A successful verification displays state: verified (code 2) for your custom domain.