# 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.

Source: https://straitlink.in/blog/android-app-links-verification-sha-256-mistakes/

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](https://developer.android.com/training/app-links/verify-applinks))

A minimal file looks like this:

```json title="/.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:

```bash
# 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](https://developer.android.com/training/app-links/verify-applinks) 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:

```bash
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](https://straitlink.in/tools/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](https://developer.android.com/training/app-links/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:

```bash
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](https://straitlink.in/blog/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](https://straitlink.in/docs/migrate-from-firebase/page-link/)), 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](https://straitlink.in/blog/page-link-links-404-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](https://straitlink.in/docs/app-links/), 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](https://developer.android.com/training/app-links/verify-applinks) and [Handling Android App Links](https://developer.android.com/training/app-links): the file format, serving rules, intent filter and the `pm` commands.
- Google Play Console Help, [Use Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756): Google re-signs Play builds with the app signing key.
- Strait fingerprint handling as documented in our [App Links docs](https://straitlink.in/docs/app-links/), and the checks in our [App Links checker](https://straitlink.in/tools/app-links-checker/).
