Links Still Open in the Browser After Sideloading an APK: Android App Links Verification and assetlinks.json, Diagnosed Step by Step
The APK installed, the app launches fine, but tapping an https link still hands you to the browser - or the Open with chooser does not list the app you just installed. Almost always this is App Links domain verification: intent-filter declarations, assetlinks.json reachability, signing certificate SHA-256 fingerprint mismatch, and the user toggle added in Android 12. A full mechanism table, runnable adb and curl commands, a nine-step diagnostic path, version differences, an FAQ, and verified internal links.
There is a particular class of problem that makes people suspect they installed a fake APK. The app is definitely there. The icon sits on the home screen, tapping it works, login works, feeds refresh, notifications arrive. But the moment you tap an https:// link in a chat message, an SMS, or a browser page, Android either sends it straight to the browser or shows an Open with chooser that does not contain the app you just installed.
So people start uninstalling and reinstalling, clearing caches, switching download sources, hunting for a "fixed" build. None of that touches the cause. If the app launches, installation succeeded. If links do not route to it, an entirely separate pipeline never completed: Android App Links domain verification.
> The key distinction: installation success and link ownership are two different systems. The first is handled by PackageManager and finishes when the package is installed. The second requires the system to make a background HTTPS request to the app's own website, compare the package name and the signing certificate fingerprint, and only then assign that domain to the app. If any link in that chain does not match, the link never reaches your app.
This article takes that chain apart, gives you a command you can run at every stage, and ends by explaining which cases are not fixable from the device at all.
Three different things: deep links, App Links, and the default-open toggle
These terms get used interchangeably, which sends the investigation in the wrong direction from the start. The distinction determines which symptom you see.
| Type | How Android decides | What happens when you tap | Who controls it |
|---|---|---|---|
| Plain deep link | Matches the scheme / host declared in the manifest; no website ownership check | Open with chooser, app listed alongside the browser | The app alone |
| Android App Link | intent-filter carries android:autoVerify="true"; the system fetches assetlinks.json and checks package name plus signing fingerprint | Verified domains open the app directly, no chooser | Website + app signature + system |
| User default-open setting | "Open supported links" is off, or the domain is not ticked | Even a verified domain goes to the browser | The user, manually |
The middle row is the important one: App Link verification requires cooperation from the app's website. It is not a local setting. No amount of clearing data on the phone changes a file on someone else's server. That is exactly why sideloaded APKs hit this so often - the APK in your hands and the certificate declared on the official site may not be the same signature.
One more diagnostic shortcut before you start. If tapping the link shows a chooser that includes your app, the intent-filter is fine and the app simply never earned "verified" status; the App Link degraded into a plain deep link. If the chooser does not list your app at all, the problem is earlier - the intent-filter did not match, or BROWSABLE was never declared. Those two cases have completely different starting points, so spend ten seconds working out which one you have.
What actually happens during verification
Since Android 6.0 (API 23), one App Links verification run looks roughly like this. Understanding the order matters more than memorising commands, because each failure produces a different observable signal.
| Stage | Trigger | What the system does | Symptom on failure | Where to observe |
|---|---|---|---|---|
| 1. Parse declaration | Install / update | Reads the manifest, finds intent-filters with autoVerify="true" plus VIEW, BROWSABLE, DEFAULT | App missing from chooser | apkanalyzer manifest print |
| 2. Collect domains | Immediately after | Extracts every android:host, filters out non-http schemes | Some domains work, others do not | Domain list in pm get-app-links |
| 3. Request verification | Async, once online | Requests https://<host>/.well-known/assetlinks.json for each host | Stuck in unverified state | Server access logs, pm get-app-links |
| 4. Validate statement | After response | Checks HTTP 200, Content-Type, no redirects, valid JSON, matching relation and package_name | legacy_failure or failed | curl -sSI |
| 5. Compare fingerprint | Immediately after | Compares sha256_cert_fingerprints against the installed app's signing certificate | First four stages pass, still unverified | apksigner verify --print-certs |
| 6. Persist result | On completion | Marks the domain verified, writes to the domain preference table | Needs a re-trigger to refresh | pm get-app-links, dumpsys package |
| 7. User toggle | At tap time | On Android 12+ also checks whether "Open supported links" is allowed | Verified but still opens in browser | App info settings |
An easily missed detail at stage 3: the request comes from the system, not from your browser. If the device was offline at install time, under aggressive battery restriction, or the domain lookup was blocked, verification fails silently and keeps the old state. No toast, no notification. That is the whole explanation behind "it did not work right after installing, then worked after a reboot."
Stage 5 deserves special attention from anyone sideloading. sha256_cert_fingerprints is the SHA-256 fingerprint of the signing certificate - not the SHA-256 of the APK file, and not the version code. People routinely compare it against the checksum printed on a download page and, unsurprisingly, never get a match.
What assetlinks.json looks like, and why Play App Signing is the biggest trap
The statement file lives at a fixed path under the site root and is a JSON array:
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77"
]
}
}
]The requirements are stricter than they look, and any single violation fails the whole check:
- It must be served over
https://with a complete, valid TLS chain; self-signed certificates do not work. - It must return HTTP 200 with no redirects at all -
http → httpsandno-www → wwwredirects count as failures too. Content-Type: application/jsonis strongly recommended.- It cannot be blocked by
robots.txt, and cannot require login, cookies, or a client certificate. - It must be a valid JSON array, with
relationset todelegate_permission/common.handle_all_urls. namespacemust beandroid_app, andpackage_namemust match the on-device package name character for character.- It should return quickly; verification requests operate on a timeout budget.
Now the trap. Most apps published on Google Play use Play App Signing: the developer signs with an upload key, then Google re-signs the artifact with a separate app signing key before distribution. So the fingerprint in the official assetlinks.json is usually the fingerprint of Google's app signing key.
That means:
- If you installed the official Play-distributed build, the fingerprints match and verification succeeds.
- If you sideloaded a developer test build, a debug build, an older release, a re-signed mod, or a build from a different distribution channel, the signing certificate differs, so the fingerprints cannot match.
- The result: stages 1 through 4 all pass, the file is reachable, the package name is correct, and stage 5 quietly fails.
Critically, this failure never produces an install error. A certificate mismatch affects "update an existing app with the same package name" and "App Links ownership"; the former surfaces as INSTALL_FAILED_UPDATE_INCOMPATIBLE, while the latter is a completely silent downgrade. So you get a perfectly functional app whose links never route - exactly the symptom described at the top.
For the same certificate mechanism showing up at install time instead, see APK signature mismatch install failures.
A nine-step diagnostic path, with a runnable command at every step
Work through these in order. Steps 1–4 are on a computer; steps 5–9 need adb connected to the device (enable Developer options and USB debugging, or use wireless debugging). Replace com.example.app and example.com with the real package name and domain.
Step 1: Confirm how the intent-filter is declared
Read the manifest straight out of the APK and look for autoVerify, BROWSABLE, and DEFAULT:
apkanalyzer manifest print app.apk | grep -A 12 -i "intent-filter"
# Expect android:autoVerify="true", android.intent.category.BROWSABLE
# and <data android:scheme="https" android:host="example.com" />Without apkanalyzer, decode the binary XML with aapt:
aapt dump xmltree app.apk AndroidManifest.xml | grep -A 20 -i "autoVerify\|BROWSABLE\|android:host"Verdict: no autoVerify at all means the app never intended to be an App Link. A chooser is the designed behaviour, not a fault. Only continue if the declaration exists.
Step 2: Confirm the actual package name on the device
adb shell pm list packages | grep -i example
adb shell pm path com.example.appA .debug or .beta suffix - or any package name other than the one you assumed - invalidates the comparison in step 4. Keep the path returned by pm path; step 5 can use it.
Step 3: Fetch the statement file from the server
curl -sSI https://example.com/.well-known/assetlinks.json
curl -sS -o /dev/null -w "code=%{http_code} type=%{content_type} redirect=%{redirect_url}\n" https://example.com/.well-known/assetlinks.json
curl -sS https://example.com/.well-known/assetlinks.json | jq .The first shows response headers, the second prints status, type, and redirect in one line, the third confirms the JSON parses. Any 301/302, any non-200, a `text/html` content type, or a `jq` parse error is an immediate failure - there is no point investigating the device further.
Step 4: Extract the signing certificate fingerprint from your APK
apksigner verify --print-certs app.apk
# Example output: Signer #1 certificate SHA-256 digest: aabbccdd...
keytool -printcert -jarfile app.apk # legacy approach, v1 signatures onlyapksigner prints colon-free lowercase hex; assetlinks.json usually uses uppercase colon-separated groups. Normalise before comparing:
apksigner verify --print-certs app.apk | grep "SHA-256" | awk '{print $NF}' \
| tr 'a-f' 'A-F' | sed 's/../&:/g;s/:$//'Compare that string character for character with jq -r '.[].target.sha256_cert_fingerprints[]'. A mismatch is the root cause - stop poking at the device.
Step 5: Read the domain verification state the system recorded
Android 12 (API 31) and later:
adb shell pm get-app-links com.example.appEach domain is followed by a state. The common values:
| State | Meaning | Next step |
|---|---|---|
verified | Verified, domain assigned to the app | Go to step 8, check the user toggle |
none / 1024 | Not yet verified, or verification incomplete | Go to step 6, re-trigger |
legacy_failure | Server file or statement did not satisfy requirements | Back to steps 3 and 4 |
denied / absent | Explicitly disallowed by user or system | Go to step 8 |
Android 11 and earlier have no pm get-app-links; use the domain preference table:
adb shell dumpsys package domain-preferred-apps
adb shell dumpsys package com.example.app | grep -i -A 10 "domain\|verification"Step 6: Re-trigger verification
adb shell pm verify-app-links --re-verify com.example.app
sleep 5
adb shell pm get-app-links com.example.appBefore triggering, make sure the device is online, not in an extreme battery-saving mode, and resolving DNS normally. Verification is asynchronous, so wait a few seconds before reading the state. If it stays unverified while steps 3 and 4 are clean, the almost certain cause is a fingerprint mismatch - the server declares a different signing key. That is inherent to a sideloaded distribution build and cannot be changed locally.
Step 7: Check who the system actually resolves the link to
adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d https://example.com/some/path
adb shell am start -W -a android.intent.action.VIEW -d https://example.com/some/pathThe first queries without launching and prints the selected component; the second actually launches and reports the Activity and timing. If the first returns a browser component, domain ownership was never established. If it returns your app but the UI still goes to the browser, step 8 is the answer.
Step 8: Check the Android 12+ "Open supported links" toggle
adb shell am start -a android.settings.APPLICATION_DETAILS_SETTINGS -d package:com.example.appIn the app info page, find "Open by default / Open supported links / Add link" and confirm the toggle is on and the target domain is ticked. On Android 12+ this is a user authorisation independent of verification: a verified domain still goes to the browser if the user has not allowed it. This is why links stopped opening for many people right after an OS upgrade.
Step 9: Rule out environment and multi-user interference
adb shell am get-current-user
adb shell pm list users
adb shell cmd package resolve-activity --brief --user 0 -a android.intent.action.VIEW -d https://example.com/xWork profiles, app clones, and secondary users each keep their own link preferences; some vendor skins also move "Open by default" into a different menu. If behaviour differs between the main user and a work profile, check the toggle per user.
Version differences that change the diagnosis
The same APK can behave differently across Android versions, so establish the OS level first:
adb shell getprop ro.build.version.release
adb shell getprop ro.build.version.sdk| Android | API | Verification model | Effect on diagnosis |
|---|---|---|---|
| 6.0 – 7.x | 23–25 | App Links introduced, one-shot verification at install | Reinstalling can re-trigger |
| 8.0 – 10 | 26–29 | Result persisted; failures persist for a long time | Needs verify-app-links or a reinstall |
| 11 and earlier | ≤30 | All-or-nothing: every host must pass | One bad host breaks every domain |
| 12 | 31 | DomainVerificationManager, per-domain decisions | Use pm get-app-links for state |
| 12+ | ≥31 | New user "Open supported links" authorisation | Verified may still not open |
| 13 – 15 | 33–35 | Finer states, user selection takes priority | Check the user toggle first |
The 11/12 boundary is the one that catches people out. On Android 11, a single unreachable statement file among the manifest's hosts downgrades every domain for the app. From Android 12 onward decisions are made per domain, so "main site links open, campaign page links do not" is a legitimate partial-success state. Check the OS version before concluding the configuration is wrong.
Command quick reference
| Goal | Command |
|---|---|
| Read autoVerify from manifest | apkanalyzer manifest print app.apk | grep -A 12 intent-filter |
| Find package name | adb shell pm list packages | grep -i example |
| Statement file headers | curl -sSI https://example.com/.well-known/assetlinks.json |
| Status and redirect | curl -sS -o /dev/null -w "%{http_code} %{redirect_url}\n" https://example.com/.well-known/assetlinks.json |
| APK signing fingerprint | apksigner verify --print-certs app.apk |
| Fingerprints in file | jq -r '.[].target.sha256_cert_fingerprints[]' assetlinks.json |
| Domain verification state | adb shell pm get-app-links com.example.app |
| Re-trigger verification | adb shell pm verify-app-links --re-verify com.example.app |
| Link resolution result | adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d https://example.com/x |
| Legacy domain preference table | adb shell dumpsys package domain-preferred-apps |
| Open app info settings | adb shell am start -a android.settings.APPLICATION_DETAILS_SETTINGS -d package:com.example.app |
FAQ
Q1: Reinstalling fixed it. Does that mean the original install was broken?
Not necessarily. Reinstalling re-triggers domain verification, so if the first attempt failed only because the device was offline or battery-restricted at install time, the reinstall simply gave it a second chance. What changed was the *timing*, not the package. pm verify-app-links --re-verify achieves the same thing without the uninstall loop.
Q2: The chooser shows my app but I have to pick it every time. Can I set it as default?
Yes - enable it in the app's "Open by default" settings. But understand that this makes a plain deep link the default handler; it is not the same as App Link verification. It only applies to links that already match, and website ownership is still unverified.
Q3: `assetlinks.json` returns 200 with the right Content-Type. Why is it still unverified?
In order of likelihood: signing certificate fingerprint mismatch (most common with sideloads), a 301/302 redirect, package_name not matching the on-device package, a wrong relation, or robots.txt blocking. Eliminate each with the commands in steps 3 and 4.
Q4: I downloaded the APK from a third-party site and links do not open. Did I get a modified build?
That symptom alone is not evidence. Any build signed with a certificate other than the one declared - including an official debug build, a beta, or an older channel build - fails verification. If you also saw a signature conflict warning at install time, that is worth checking the source; see APK install failed troubleshooting.
Q5: Will clearing cache, clearing data, or force-stopping help?
Almost never. Verification results live on the system side (DomainVerificationManager / the domain preference table), not in the app's own data directory. Clearing app data only costs you your login session. The correct way to retry is the re-trigger in step 6.
Q6: Why did links stop opening after upgrading to Android 12?
Because Android 12 added the user authorisation step and switched to per-domain decisions. Some domains need to be re-ticked under "Open supported links" after the upgrade. Check pm get-app-links, then tick them in app info.
Q7: Only `http://` links fail while `https://` works. Is that normal?
Yes. App Links require https, and cleartext traffic has been disabled by default since Android 9. If the manifest declares only the https scheme, http links are not supposed to match.
Q8: I run the site. How long until a change to `assetlinks.json` takes effect?
The server change is immediate for new verification requests, but devices cache the result. Ask users to re-trigger verification or reinstall; state usually refreshes within seconds to minutes. Do not expect it to recover on its own.
Q9: Can switching to a different APK version fix this?
Only if you switch to a build signed with the certificate the site declares. Version number does not determine the fingerprint, so compare with apksigner verify --print-certs before trying another build - it saves a lot of pointless downloads. Version targeting interacts with other system behaviour too; see targetSdkVersion explained.
Q10: Is this related to split APKs or App Bundles?
Indirectly. A single logical app may be delivered as a base APK plus configuration splits, but verification reads the manifest and the signing certificate of the package as installed, regardless of how many APKs it was assembled from. If you are installing .apks or .xapk bundles, see how to install split APKs on Android first and make sure the assembled install uses the expected certificate.
When the fix is not on your device
Once you have walked the nine steps, three conclusions mean you should stop tweaking the phone:
- The official `assetlinks.json` is missing, redirects, or is misconfigured - only the site operator can fix it.
- The signing certificate fingerprint does not match (sideloaded non-official build) - you need a build signed with the declared key, or you accept that links will not open automatically.
- The app never declared `autoVerify` - a design choice; the chooser is expected behaviour.
In the first two cases the practical alternatives are: paste the link into the app manually, use the app's own open-in-app flow, or set it as the default handler for a plain deep link. Reinstalling repeatedly, switching download sources, and clearing data will not change a remote file or a certificate.
This also gets confused with other "installed, but something is off" problems that have entirely different causes. No launcher icon is a launcher registration issue, covered in installed APK shows no app icon. Crashing on launch is a runtime problem, covered in APK installs but crashes on launch. A stalled install is a PackageInstaller session problem, covered in APK stuck on installing. Classify the symptom before picking a guide.
Further reading
- Modern unknown-sources install settings: sort out the permission chain before sideloading
- APK install failed troubleshooting: the same certificate mechanism at install time
- APK stuck on installing: a different failure mechanism in the install phase
- How to install split APKs on Android: certificate behaviour for assembled bundles
- targetSdkVersion explained: why OS level changes system behaviour
- Downloaded APK not found (scoped storage): locating files under scoped storage
- Notifications not showing after install: another post-install permission issue
- Storage still full after uninstall: cleaning up residual files
- APK installs but crashes on launch: logcat diagnosis for startup crashes
Bottom line
A link not opening your app is never "a bad install" - it is domain ownership that was never established. Localise it in this order: confirm autoVerify with apkanalyzer, confirm assetlinks.json is reachable and redirect-free with curl, compare the signing certificate fingerprint with apksigner, read the system state with pm get-app-links, re-trigger with verify-app-links, then check the Android 12+ user toggle. Those nine steps always identify the broken link in the chain, which beats reinstalling and hoping.
For anyone sideloading APKs, the one thing worth remembering is: the signing certificate fingerprint is determined by the distributed build, not by the version number. Whichever certificate the official site declares is the one your APK must be signed with. Otherwise the chain stops quietly at stage 5 - no error, no warning, just a link handed back to the browser.