android:autoVerify="true"<\/code>. Android then verifies that claim by checking whether your domain publishes a file that acknowledges your app's signing certificate.<\/p>\n\n\n\nThis is a two-way handshake: your app says "I handle URLs on this domain," and your domain says "I authorize this app (identified by its signing certificate) to handle my URLs." Both sides must agree, or verification fails.<\/p>\n\n\n\n
The file Android checks is assetlinks.json<\/code>, hosted at https:\/\/yourdomain.com\/.well-known\/assetlinks.json<\/code>. The path and filename are fixed by the protocol.<\/p>\n\n\n\nWhat the assetlinks.json File Must Contain<\/h2>\n\n\n\n
The minimum valid structure for a single app:<\/p>\n\n\n\n
[{\n "relation": ["delegate_permission\/common.handle_all_urls"],\n "target": {\n "namespace": "android_app",\n "package_name": "com.yourcompany.app",\n "sha256_cert_fingerprints": [\n "A1:B2:C3:D4:E5:F6:..."\n ]\n }\n}]\n<\/code><\/pre>\n\n\n\nThe sha256_cert_fingerprints<\/code> array accepts multiple fingerprints, which matters if you have both a debug build and a release build, or if you use multiple signing keys. Each fingerprint is a colon-delimited uppercase hex string.<\/p>\n\n\n\nTo get the fingerprint for your release keystore:<\/p>\n\n\n\n
keytool -list -v \\\n -keystore \/path\/to\/release.keystore \\\n -alias your-alias\n<\/code><\/pre>\n\n\n\nIf your app is signed by Google Play (using Play App Signing), get the fingerprint from the Play Console under Setup > App integrity > App signing key certificate. The fingerprint from your upload key will not match what Play uses to sign the distributed APK.<\/p>\n\n\n\n
This is one of the most common causes of verification failure: the fingerprint in assetlinks.json<\/code> matches the upload key, not the Play signing key.<\/p>\n\n\n\nServer Requirements for Verification<\/h2>\n\n\n\n
![\"Tolinku](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/platform-platform-domains.png\")
<\/p>\n\n\n\n
Android's verification agent has specific requirements for how your server must respond. All of these must be true:<\/p>\n\n\n\n
HTTPS only.<\/strong> The file must be accessible via HTTPS. HTTP is not checked. Your SSL certificate must be valid (not expired, not self-signed, not a certificate for a different domain).<\/p>\n\n\n\nStatus 200.<\/strong> The server must return HTTP 200. Redirects are not followed. If \/.well-known\/assetlinks.json<\/code> redirects to another path, verification will fail. This catches setups where a CDN redirects bare paths, or where www.yourdomain.com<\/code> redirects to yourdomain.com<\/code> but the intent filter specifies the former.<\/p>\n\n\n\nCorrect Content-Type.<\/strong> The response must have Content-Type: application\/json<\/code>. Some servers serve files from .well-known\/<\/code> with application\/octet-stream<\/code> or text\/plain<\/code>. Both will cause verification to fail.<\/p>\n\n\n\nNo authentication.<\/strong> The file must be publicly accessible without any authentication headers, cookies, or IP restrictions. Android's verification system cannot authenticate.<\/p>\n\n\n\nReasonable response time.<\/strong> Android has a timeout for the verification check. If your server is slow or the file is behind a CDN edge that takes too long on first request, verification may time out.<\/p>\n\n\n\nValid JSON.<\/strong> The file must parse as valid JSON. A trailing comma, unclosed bracket, or encoding issue will cause the verification to fail silently.<\/p>\n\n\n\nYou can test server compliance with:<\/p>\n\n\n\n
curl -v "https:\/\/yourdomain.com\/.well-known\/assetlinks.json"\n<\/code><\/pre>\n\n\n\nCheck the response code, Content-Type header, and that the body is valid JSON.<\/p>\n\n\n\n
For multi-domain setups, each domain needs its own assetlinks.json<\/code>. A common mistake is hosting the file only on the primary domain when intent filters cover subdomains.<\/p>\n\n\n\nWhen Android Runs Verification<\/h2>\n\n\n\n
Android does not verify on every link click. Verification happens at specific points:<\/p>\n\n\n\n
On app install.<\/strong> When your app is installed (or updated), Android reads the intent filters with android:autoVerify="true"<\/code> and schedules verification for each unique domain.<\/p>\n\n\n\nImmediately after install.<\/strong> Android attempts verification shortly after the install completes, using background network access.<\/p>\n\n\n\nOn periodic re-verification.<\/strong> Android re-verifies periodically to detect if the domain's assetlinks.json<\/code> has changed. This is not on a fixed schedule and is not user-visible.<\/p>\n\n\n\nAfter a failed verification.<\/strong> If verification fails, Android does not continuously retry. It marks the domain as unverified and may attempt again at the next install or update.<\/p>\n\n\n\nThis timing has practical implications. If you ship your app before your server is ready to serve assetlinks.json<\/code>, the app will install without App Link verification. Users who installed during that window will have unverified links until they reinstall or update the app.<\/p>\n\n\n\nThe verification result is stored per domain per app. It is not re-checked at launch time.<\/p>\n\n\n\n
Verification States<\/h2>\n\n\n\n
You can inspect the current verification state using ADB:<\/p>\n\n\n\n
adb shell pm get-app-links com.yourcompany.app\n<\/code><\/pre>\n\n\n\nOutput looks like:<\/p>\n\n\n\n
com.yourcompany.app:\n ID: a1b2c3d4\n Signatures: [AA:BB:CC:...]\n Domain verification state:\n yourdomain.com: verified\n sub.yourdomain.com: failed\n<\/code><\/pre>\n\n\n\nThe possible states are:<\/p>\n\n\n\n
\nverified<\/code>: Android confirmed the domain and the app are linked.<\/li>\nfailed<\/code>: Verification was attempted and failed.<\/li>\npending<\/code>: Verification has been scheduled but not yet completed.<\/li>\nnone<\/code>: No verification has been attempted for this domain.<\/li>\n<\/ul>\n\n\n\nIf you see failed<\/code>, the next step is determining why. On Android 12 and higher, the Domain Verification API<\/a> lets you request re-verification for testing:<\/p>\n\n\n\nadb shell pm set-app-links --package com.yourcompany.app 0 all\nadb shell pm verify-app-links --re-verify com.yourcompany.app\n<\/code><\/pre>\n\n\n\nThe first command resets the verification state. The second triggers a fresh verification attempt. Wait a few seconds, then run get-app-links<\/code> again to see the new state.<\/p>\n\n\n\nMultiple Domains<\/h2>\n\n\n\n
If your app handles URLs on multiple domains, each domain needs its own assetlinks.json<\/code> and each domain must be listed in your intent filters.<\/p>\n\n\n\n![\"Android](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/doc-android-add-domains-dialog.svg\")
<\/p>\n\n\n\n
Source: Android Developer Documentation<\/a><\/em><\/p>\n\n\n\n<intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https" android:host="yourdomain.com" \/>\n <data android:scheme="https" android:host="www.yourdomain.com" \/>\n <data android:scheme="https" android:host="partner.yourdomain.com" \/>\n<\/intent-filter>\n<\/code><\/pre>\n\n\n\nNote that yourdomain.com<\/code> and www.yourdomain.com<\/code> are treated as distinct domains. Both need intent filter entries and both need assetlinks.json<\/code> files. If www<\/code> redirects to the apex domain, you still need the assetlinks.json<\/code> on the www<\/code> domain to be served directly (not via redirect).<\/p>\n\n\n\nFor subdomains controlled by a platform or CDN, verify that each subdomain can independently serve the file. Some CDN configurations serve the file correctly on the primary domain but not on subdomains.<\/p>\n\n\n\n
The Include Mechanism<\/h2>\n\n\n\n
If you manage many subdomains, maintaining assetlinks.json<\/code> on each one is cumbersome. The Digital Asset Links protocol supports an include<\/code> statement:<\/p>\n\n\n\n[{\n "include": "https:\/\/yourdomain.com\/.well-known\/assetlinks.json"\n}]\n<\/code><\/pre>\n\n\n\nA subdomain's assetlinks.json<\/code> can include the primary domain's file. Android will follow the include and use the authoritative file. Includes can be nested, but keep the chain short to avoid timeout issues.<\/p>\n\n\n\nThis is useful when you have many subdomains (for example, per-user subdomains in a SaaS product) and want to maintain a single authoritative file.<\/p>\n\n\n\n
Wildcards<\/h2>\n\n\n\n
Android App Links do not support wildcard domains in intent filters. You cannot specify android:host="*.yourdomain.com"<\/code> and have it match all subdomains. Each subdomain must be explicitly listed.<\/p>\n\n\n\nThis is a meaningful constraint for apps with dynamic subdomains. One common pattern is to not use subdomains for the deep-linked paths, and instead use path parameters: yourdomain.com\/user\/username\/<\/code> rather than username.yourdomain.com\/<\/code>.<\/p>\n\n\n\nWhy Verification Fails in Production<\/h2>\n\n\n\n
Beyond the server configuration issues covered above, these are the most common production verification failures:<\/p>\n\n\n\n
Play App Signing fingerprint mismatch.<\/strong> This is the single most common cause. If your app is enrolled in Play App Signing (which is now the default for new apps), the fingerprint in assetlinks.json<\/code> must match the signing key that Google Play uses, not your upload key. Get the correct fingerprint from the Play Console.<\/p>\n\n\n\nCDN caching the wrong response.<\/strong> If you initially served a 404 or wrong Content-Type, and a CDN cached that response, Android may see the cached error response even after you fix the underlying file. Purge your CDN cache after making changes.<\/p>\n\n\n\nDifferent fingerprints for debug and release.<\/strong> Debug builds use a different signing certificate than release builds. If you test with a debug APK against a assetlinks.json<\/code> that only has the release fingerprint, verification will fail on your test device.<\/p>\n\n\n\nFile served only on certain paths.<\/strong> Some routing configurations only handle certain paths. Verify that \/.well-known\/assetlinks.json<\/code> is not being caught by a catch-all redirect rule or authentication middleware.<\/p>\n\n\n\nClock skew on SSL certificates.<\/strong> If your server's clock is significantly wrong, SSL certificate validation may fail, causing the HTTPS request to fail before the file is even fetched.<\/p>\n\n\n\nVerification on Android 11 and Earlier<\/h2>\n\n\n\n
The verification behavior changed with Android 12. On Android 11 and earlier, a single failed domain verification would cause all App Links in the same intent filter to fall back to browser behavior. On Android 12 and later, each domain is verified independently.<\/p>\n\n\n\n
If you support Android 11, split intent filters by domain rather than combining them:<\/p>\n\n\n\n
<!-- Separate intent filter per domain for Android 11 compatibility -->\n<intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https" android:host="yourdomain.com" \/>\n<\/intent-filter>\n\n<intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https" android:host="www.yourdomain.com" \/>\n<\/intent-filter>\n<\/code><\/pre>\n\n\n\nThis ensures a verification failure on one domain does not affect the other.<\/p>\n\n\n\n
Testing Verification Locally<\/h2>\n\n\n\n
During development, you cannot verify against localhost<\/code> or an internal IP. App Links require a publicly accessible HTTPS domain. Options for local testing:<\/p>\n\n\n\n\n- Use a service like ngrok to expose a local server via a public HTTPS URL<\/li>\n
- Deploy to a staging environment with your real domain under a subdomain<\/li>\n
- Manually override App Link handling during development using ADB to set the domain as verified without actual network verification<\/li>\n<\/ul>\n\n\n\n
The ADB override approach is useful for UI testing:<\/p>\n\n\n\n
adb shell pm set-app-links-user-selection \\\n --user 0 \\\n --package com.yourcompany.app \\\n enabled \\\n yourdomain.com\n<\/code><\/pre>\n\n\n\nThis tells Android to route App Links for that domain to your app without verification, which is useful for automated tests that do not have a live server.<\/p>\n\n\n\n
For a practical setup guide covering hosting and configuration, see the Android App Links developer documentation<\/a> and the configuring Android guide<\/a>. If you are working through verification failures, the troubleshooting guide<\/a> has a diagnostic checklist.<\/p>\n\n\n\nSummary<\/h2>\n\n\n\n
Android App Link verification is straightforward when everything is configured correctly, and opaque when something is wrong. The key points:<\/p>\n\n\n\n
\n- The
assetlinks.json<\/code> file must be served at exactly the right path, with HTTPS, status 200, and Content-Type: application\/json<\/code><\/li>\n- The SHA-256 fingerprint must match the certificate used to sign the distributed APK, not your upload key or debug key<\/li>\n
- Verification happens at install and update time, not at click time<\/li>\n
- Each domain is verified independently on Android 12 and later<\/li>\n
adb shell pm get-app-links<\/code> is your primary diagnostic tool<\/li>\n- Redirects on the
assetlinks.json<\/code> path will silently fail verification<\/li>\n<\/ul>\n\n\n\nGetting verification right once means your deep links work reliably across all Android versions your app supports. The investment in understanding this process pays off every time a user clicks a link and lands exactly where they expected.<\/p>\n","protected":false},"excerpt":{"rendered":"
Android App Link verification is the mechanism that lets your app intercept HTTPS URLs without a chooser dialog. This deep dive covers the full verification process, server requirements, timing, retry behavior, and how to diagnose failures.<\/p>\n","protected":false},"author":2,"featured_media":558,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Android App Link Verification: How It Works (2026)","rank_math_description":"A deep dive into Android App Link verification. Learn server requirements, when Android verifies, retry behavior, multi-domain setup, and how to fix verification failures.","rank_math_focus_keyword":"app link verification process","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-android-app-link-verification-process.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-android-app-link-verification-process.png","footnotes":""},"categories":[10],"tags":[25,23,92,93,87,91],"class_list":["post-559","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-android","tag-android","tag-app-links","tag-assetlinks","tag-security","tag-troubleshooting","tag-verification"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/559","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=559"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/559\/revisions"}],"predecessor-version":[{"id":560,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/559\/revisions\/560"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/558"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=559"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=559"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=559"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}