Deep links, and why a website app wants them
Every link to your website that someone taps on a phone — in an email, a message, a search result — opens in the browser. Once your website is also an app, that is the wrong place: the visitor has your app installed, and the link opens a browser tab beside it. Android App Links fix this. When they are set up, tapping https://www.example.com/products/42 opens your app directly on that page, with no "open with" chooser.
It takes two things that have to agree with each other: an intent filter inside the app saying "I handle links on this domain", and a file on the domain — /.well-known/assetlinks.json — saying "this app, signed with this key, is allowed to". Android checks the file at install time and, if it verifies, routes the links without asking.
The three fields
Domain
The host exactly as it appears in your links. example.com and www.example.com are different hosts to Android: if your site answers on both, list both, and host the JSON file on both.
Package name
The applicationId you gave the builder. It has to match the installed app byte for byte, which is one more reason the package name can never change after publishing.
SHA-256 fingerprint
The fingerprint of the certificate the installed app is signed with. For an app on Google Play that is the App signing key certificate in Play Console (Test and release → App integrity), not your upload key — Play re-signs the app before it reaches phones. For an APK you distribute yourself, it is the certificate in your keystore: keytool -list -v -keystore your.jks prints it.
Claiming some paths, not all
Leaving the paths empty claims every HTTPS link on the domain, which is right for most sites. Use paths when only part of the site lives in the app — /shop/* but not /blog/* — so blog links still open in the browser. Android's pathPrefix is a plain string prefix, so /shop also matches /shopping; add the trailing slash if that matters.
Why verification fails
- Wrong certificate. The upload-key fingerprint instead of the app-signing one. This is the cause nine times out of ten.
- The file redirects. A
www→ bare redirect, an HTTP → HTTPS redirect, a trailing-slash rewrite. Android follows none of them. - Wrong content type. It must be served as
application/json. Some static hosts serve unknown extensions astext/plain. - Blocked by robots or a firewall. Android's fetch is not a browser; a WAF that challenges unknown user agents blocks it.
- Cached failure. Android checks once at install. After fixing the file, reinstall the app or run
adb shell pm verify-app-links --re-verify.
adb shell pm get-app-links prints the state per domain — verified, none or an error code — and is the first thing to run when links keep opening in the browser.
Deep links and the builder
The builder does not yet expose an App Links option; the generated app opens your site and links inside it stay in the app, but system-wide links still go to the browser. This tool is here for people who take the generated project further, and so the setup is ready the day the option ships. The deep links guide covers the whole flow, including iOS Universal Links for when you go there.