BlogAndroid

Android App Links verification: the SHA-256 mistakes that break it

· 6 min read · By the Strait team

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:

/.well-known/assetlinks.json
[{
  "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:

Terminal
# 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 signingReport

Mistake 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.json redirects to www.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:

Terminal
curl -sI https://hilltop.strait.link/.well-known/assetlinks.json
# HTTP/2 200
# content-type: application/json

Or 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:

XML
<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 http or https scheme. Android accepts either in a verified filter, but it always fetches assetlinks.json over HTTPS (Android: configure assetlinks).
  • The host spelled exactly as the domain that serves the file. example.com and www.example.com are different hosts, and each needs its own file.

Mistake 6: testing the wrong way

Two testing habits produce false failures:

  1. 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.
  2. 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:

Terminal
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: verified

If 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.json lists 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", https and the exact host
  • You reinstalled or ran pm verify-app-links --re-verify after 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