Android App Links verification: the SHA-256 mistakes that break it
Android App Links fail silently: the link just opens the browser. Often the cause is a SHA-256 fingerprint in assetlinks.json that doesn't match the certificate on the phone. Here is how to find the right fingerprints, and the other mistakes that break verification.
Android App Links have one failure mode, and it's silent. When verification fails, nothing crashes and nothing logs an error in your app. The link simply opens in the browser instead of your app. You get no hint about why.
A frequent cause, and the one this post starts with, is a SHA-256 certificate fingerprint that doesn't match the build on the phone. This post explains where the right fingerprints come from, then walks through the other mistakes that break verification, with the commands to check each one.
How verification works, in one paragraph
When your app is installed, Android looks at every intent filter marked android:autoVerify="true", takes each https host in them, and fetches https://<host>/.well-known/assetlinks.json. That file says which apps may open links on the domain, by package name and SHA-256 fingerprint of the signing certificate. If the package name and one of the fingerprints match the installed app, the domain is verified and taps on its links open your app directly. If not, they open the browser. (Android: verify App Links)
A minimal file looks like this:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.yourco.app",
"sha256_cert_fingerprints": [
"FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
]
}
}]The fingerprint list is where most problems start.
Mistake 1: only the debug fingerprint
During development you sign with the debug keystore that Android Studio creates for you. Its fingerprint goes into assetlinks.json, the link opens your debug build, and everyone moves on. Then a release build, signed with a different key, opens the browser.
Every build is signed by exactly one certificate, and the file must list the fingerprint of the certificate that signed the build on that phone. In practice that's up to three:
| Build on the phone | Signed by | Where to get the SHA-256 |
|---|---|---|
| Debug build from Android Studio | Your debug keystore | keytool on ~/.android/debug.keystore, or ./gradlew signingReport |
| Release build you install yourself (APK or bundle from your machine) | Your upload key | keytool on your upload keystore, or ./gradlew signingReport |
| Build installed from Google Play (internal testing included) | Google's app signing key | Play Console → your app → App integrity → App signing |
List all of them. There's no harm in having several fingerprints in the array.
To read a fingerprint from a keystore:
# Debug keystore (the standard alias and passwords Android Studio uses)
keytool -list -v -keystore ~/.android/debug.keystore \
-alias androiddebugkey -storepass android -keypass android | grep SHA256
# Or let Gradle print every variant's signing certificate
./gradlew signingReportMistake 2: the upload key instead of the Play App Signing key
This is the big one. With Play App Signing, which Google Play uses for new apps, you don't sign the build that users install. Google does. You sign the bundle with your upload key, Google checks that signature, and then signs the app it delivers with an app signing key that Google holds.
So a Play-installed build carries Google's certificate, not yours. If assetlinks.json lists only your upload key's fingerprint, App Links work when you sideload a release build from your machine and fail for every user who installs from Play. It's maddening because "the release build works on my phone".
The fix is to copy the SHA-256 certificate fingerprint shown under App signing key certificate in Play Console → App integrity → App signing, and add it to the file. Play Console shows the upload key certificate on the same page; you can list both.
Mistake 3: SHA-1, or the wrong format
keytool and Play Console show several fingerprints for the same certificate: MD5, SHA-1 and SHA-256. App Links need the SHA-256 one: 32 bytes, written as 32 pairs of hex digits separated by colons. A 20-pair value is SHA-1 and will never match.
Google's documentation writes fingerprints as uppercase hex pairs joined by colons, like the example above. Copying from a terminal can bring in stray spaces, a SHA256: prefix or a line break. When you save fingerprints in Strait, we normalise what you paste into that exact form (32 uppercase pairs joined by colons), drop duplicates, and refuse anything that isn't a SHA-256 fingerprint, so a SHA-1 can't slip through.
Mistake 4: the file can't be fetched cleanly
Android's verifier is strict about how the file is served. The Android documentation asks for:
- HTTPS, on exactly the host in your intent filter.
- No redirects. If
https://example.com/.well-known/assetlinks.jsonredirects towww.example.com, or to a login page, verification fails. Content-Type: application/json.- Valid JSON. A trailing comma breaks it.
Check it with curl, which shows the status code, the content type and any redirect:
curl -sI https://hilltop.strait.link/.well-known/assetlinks.json
# HTTP/2 200
# content-type: application/jsonOr paste the domain into our free App Links checker. It fetches assetlinks.json (and the iPhone apple-app-site-association file) and explains each problem it finds: a missing file, a redirect, the wrong content type, a malformed fingerprint or package name.
Mistake 5: the intent filter doesn't match
Verification only runs for intent filters that ask for it. Check that yours has:
<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="hilltop.strait.link" />
</intent-filter>android:autoVerify="true"on the filter.- An
httporhttpsscheme. Android accepts either in a verified filter, but it always fetchesassetlinks.jsonover HTTPS (Android: configure assetlinks). - The host spelled exactly as the domain that serves the file.
example.comandwww.example.comare different hosts, and each needs its own file.
Mistake 6: testing the wrong way
Two testing habits produce false failures:
- Typing or pasting the link into Chrome's address bar. Chrome treats a URL typed into its address bar as browsing, not a link tap, and normally keeps it in the browser. Tap the link from a chat or email app instead.
- Not re-verifying after a change. Android checks the file when the app is installed. After you fix
assetlinks.json, reinstall the app or ask Android to verify again.
On Android 12 and later, adb shows the verification state per domain and can trigger a fresh check:
adb shell pm verify-app-links --re-verify com.yourco.app
adb shell pm get-app-links com.yourco.app
# Look for: hilltop.strait.link: verifiedIf the state is 1024 or none instead of verified, Android couldn't verify the domain. Go back through mistakes 1 to 5. Every state get-app-links can print, and the causes that aren't about fingerprints, are in Android App Links verification failed.
Mistake 7: forgetting that the domain changed
If you moved off Firebase Dynamic Links, your old intent filters point at yourapp.page.link. Google still serves page.link's assetlinks.json today, so keeping that filter lets people who have your app open it from old links (how), but Google can stop at any time. The new link domain needs its own intent filter and its own assetlinks.json with your fingerprints. People still running an old version of your app won't have the new filter, so a tap there falls back to the browser, the store or your website. Our page.link migration checklist covers that cleanup.
The short checklist
assetlinks.jsonlists the SHA-256 of every certificate: debug, upload, and the Play App Signing key- Fingerprints are SHA-256 (32 pairs), not SHA-1
- The file is served over HTTPS on the exact host, with no redirects, as
application/json - The intent filter has
android:autoVerify="true",httpsand the exact host - You reinstalled or ran
pm verify-app-links --re-verifyafter changing the file - You tested by tapping, not by typing into the address bar
How Strait handles the file for you
On Strait, your link domain serves assetlinks.json for you, built from the package name and the fingerprints you save in Dashboard → Apps & stores. It returns 404 until those fields are filled in, and fingerprints are normalised and checked when you save. The setup steps, including where each fingerprint comes from, are in our App Links & Universal Links docs, and our own Android test phone runs with App Links verified on the same setup.
Sources and how we checked
- Android Developers, Verify Android App Links and Handling Android App Links: the file format, serving rules, intent filter and the
pmcommands. - Google Play Console Help, Use Play App Signing: Google re-signs Play builds with the app signing key.
- Strait fingerprint handling as documented in our App Links docs, and the checks in our App Links checker.