Android App Links not working

Definition

Android App Links fail when the system cannot verify that a domain and an app belong to the same owner, at which point tapped links open in the browser instead of the app with no error shown to the user.

Verification is a silent process: it runs at install time, it either succeeds or it does not, and nothing surfaces to the user either way. That makes the failure hard to reason about from the outside and trivial to diagnose from the inside — a single adb command tells you the exact verification state of every domain your app claims. Start there, then work down this list.

Get the verification state first

Do not guess. Android will tell you precisely which domains verified and which did not, and the answer usually points straight at the cause.

adb shell pm get-app-links com.example.shop

# com.example.shop:
#   ID: 8f3c1e40-...
#   Signatures: [AB:CD:EF:...]
#   Domain verification state:
#     example.com: verified
#     www.example.com: 1024

# Ask the system to re-run verification for every declared domain
adb shell pm verify-app-links --re-verify com.example.shop

# Then re-read the state (verification is asynchronous — give it a few seconds)
adb shell pm get-app-links com.example.shop

The causes, in order of how often they are the real one

1. The SHA-256 fingerprint is from the wrong key. This is the cause more often than everything else combined. If your app is distributed through Google Play with Play App Signing — the default — Google re-signs your app with a key you do not hold. The fingerprint in assetlinks.json must be the app signing key, not the upload key you sign with locally. Find it in Play Console under Test and release → Setup → App signing. The upload certificate is listed on the same screen, which is exactly why the wrong one gets copied.

# Debug builds — the shared debug keystore
keytool -list -v \
  -keystore ~/.android/debug.keystore \
  -alias androiddebugkey -storepass android -keypass android

# A release keystore you hold
keytool -list -v -keystore release.jks -alias upload

# What Google actually ships: Play Console →
#   Test and release → Setup → App signing → App signing key certificate

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.shop",
      "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",
        "7B:14:12:6C:1A:99:2E:5B:57:B1:0F:D8:D1:C2:24:9A:8D:4C:03:5F:9E:B7:22:A1:44:8E:D0:6C:19:33:F0:2B"
      ]
    }
  }
]

2. `android:autoVerify="true"` is missing. Without it, the intent filter still lets your app appear in the disambiguation dialog, but the system never attempts verification and never makes your app the default handler. The attribute goes on the intent filter, not on the activity, and only needs to appear on one filter per app.

3. The intent filter is incomplete. It needs the VIEW action, both the BROWSABLE and DEFAULT categories, and an https scheme. Missing BROWSABLE means the link cannot be opened from a browser at all — which is the entire use case. Only http and https schemes are ever verified; a custom URI scheme is not an App Link and is not verified.

<activity
    android:name=".MainActivity"
    android:exported="true">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="https" android:host="example.com" />
        <data android:scheme="https" android:host="www.example.com" />
    </intent-filter>
</activity>

4. `assetlinks.json` is unreachable, redirected, or the wrong content type. It must be at https://example.com/.well-known/assetlinks.json, served as application/json, over a valid certificate, and reachable with no redirects — Google documents that requirement as explicitly as Apple does. The failure is the same shape as an AASA file not found, and usually has the same cause: a canonicalisation rule or a WAF nobody associated with the app. See how to validate assetlinks.json for the checks.

5. You changed the file after the app was installed. Verification runs at install time. Fixing assetlinks.json on the server changes nothing for an app already on the device until it is reinstalled, updated, or explicitly re-verified with pm verify-app-links --re-verify. Most reports of "the fix did not work" are this.

6. The user turned it off, or another app claimed the domain. Under Settings → Apps → your app → Open by default, a user can disable verified link handling, and it stays disabled. On Android 12 and later the same screen shows which links the app is approved to open, which makes it a fast way to confirm what the system thinks independently of adb.

7. One bad host used to fail every host. Before Android 12, if any host in an autoVerify intent filter failed verification, *all* of them failed — so a stale staging domain in the manifest silently broke the production one. Android 12 changed this to per-host verification. If you support Android 11 or earlier, audit the manifest for hosts you no longer serve a statement file from.

8. Verification ran while the device had no usable network. It is a network call at install time, and it can fail for reasons that have nothing to do with your configuration. Android retries, but the retry schedule is not immediate. --re-verify on a connected device rules this in or out in seconds.

9. The package name does not match. package_name in assetlinks.json is the applicationId from your Gradle configuration, which is not necessarily the Java package your source lives in — and build variants with applicationIdSuffix (.debug, .staging) produce a different one for every variant. Each needs its own statement in the file.

Why `adb shell am start` tells you nothing

The near-universal way to test a deep link is also the one that hides the failure you are looking for. Sending an explicit VIEW intent matches on the intent filter alone — it never consults domain verification, so a completely unverified App Link opens the app perfectly and you conclude it works.

# Tests intent filter matching and your in-app routing only.
# This SUCCEEDS even when domain verification has failed.
adb shell am start -W -a android.intent.action.VIEW \
  -d "https://example.com/products/42" com.example.shop

# Tests what actually happens to a real tap: no package, so the system
# resolves it the way it would from a browser or a chat app.
adb shell am start -W -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE \
  -d "https://example.com/products/42"