If an Android App Link opens the browser, Android either did not verify your domain or something on the device sent the link elsewhere. Verification runs in the background and shows no error. Start with the command that shows the verification state, then work through the causes below.
Check the verification state
On Android 12 and higher, this prints each host your app declares and its state:
adb shell pm get-app-links com.example.app
The states Android documents:
verified· the domain is verified for your app.none· nothing recorded yet. Wait a few minutes and verify again.approvedordenied· forced, usually by a shell command.migrated· kept from legacy verification.restored· approved after a data restore.legacy_failure· rejected by the legacy verifier. The reason is not reported.system_configured· approved by the device configuration.1024or higher · a custom error code from the device's verifier. Check that the device is online and verify again.
If the state is verified and links still open the browser, look at the device
(cause 5). Any other state points at the manifest or the file. The
commands cheatsheet has these commands ready to copy.
Cause 1: the manifest does not request verification
Android only verifies intent filters that have the VIEW action, the
DEFAULT and BROWSABLE categories, an http or
https scheme, and android:autoVerify="true":
<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="example.com" />
</intent-filter>
The Intent-Filter Generator builds this block for a URL pattern.
Cause 2: assetlinks.json is not served correctly
Android fetches https://example.com/.well-known/assetlinks.json for each host.
Google's documentation sets three rules:
- "The
assetlinks.jsonfile is served with content-typeapplication/json." - "The
assetlinks.jsonfile must be accessible over an HTTPS connection, regardless of whether your app's intent filters declare HTTPS as the data scheme." - "The
assetlinks.jsonfile must be accessible without any redirects (no 301 or 302 redirects)."
A browser follows redirects, so the file can look fine in a browser and still fail verification. Check the response headers instead:
curl -sSI https://example.com/.well-known/assetlinks.json
You want status 200, no Location header, and
content-type: application/json.
Cause 3: the package name or fingerprint does not match
A minimal file:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [
"14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
]
}
}]
package_name must be the applicationId of the installed build,
including any suffix such as .debug. sha256_cert_fingerprints must
contain the SHA-256 fingerprint of the certificate that signed the installed app. With Play App
Signing, apps installed from Play are signed with the app signing key that Google holds, not your
upload key. The field is a list, so you can include more than one fingerprint.
Cause 4: verification has not run again since your fix
On Android 14 and lower, Android verifies when the app is installed or updated. On Android 15 and higher it also verifies again in the background, and Google says changes can take up to seven days to reach devices. To check a fix right away on Android 12 or higher, reset the state and verify again:
adb shell pm set-app-links --package com.example.app 0 all adb shell pm verify-app-links --re-verify com.example.app
Wait a few minutes, then run pm get-app-links again. Reinstalling the app also
triggers verification. Server caches can still serve the old file for a while.
Cause 5: the domain is verified, but the device sends the link elsewhere
- An in-app browser. Some apps open links in their own browser view, so the link never reaches the system. Test from a QR code or a plain text message.
- Open by default is off. In the app's Open by default settings, the user can turn off Open supported links or individual domains.
To send the intent to the system directly, see the adb testing guide.
Checklist
- Run
pm get-app-linksand read the state. - The intent filter has
autoVerify="true",VIEW,DEFAULTandBROWSABLE. assetlinks.jsonis at/.well-known/, over HTTPS, asapplication/json, with no redirects.package_namematches the installedapplicationId.- The fingerprint matches the key that signed the installed app.
- After a change, reset and verify again, or reinstall.
- Test with a tap from a QR code, for example with the Deep Link Tester.
Keep reading
-
App Links vs Deep Links vs Universal Links
How the three link types differ and how each is verified.
-
Test a deep link with adb
Send the intent to the system from a terminal.
Official docs
-
Android · Verify App Links
autoVerify, the assetlinks.json file, and the domain states.
-
Digital Asset Links
The statement list format behind assetlinks.json.