Android App Links: Verify the Correct Asset Links URL

To verify an Android App Link’s Digital Asset Links URL, open https://YOUR_DOMAIN/.well-known/assetlinks.json in a browser or fetch it with a command-line tool, then confirm that it returns valid JSON containing the correct Android package name and signing-certificate SHA-256 fingerprint. Use the exact host in the link you are testing: each hostname, including a subdomain, must serve its own matching file over HTTPS.

What the asset links URL does

Android App Links are HTTP or HTTPS links that an Android app can open directly when the app has verified its association with the website. The website publishes that association as a Digital Asset Links statement, usually in a file named assetlinks.json. Android checks the statement against the app’s declared web hosts and its installed signing identity.

The URL is not an arbitrary endpoint, an API route, or a page on your app’s own domain. Its required path is:

https://hostname/.well-known/assetlinks.json

For example, if your link is https://shop.example.com/products/42, check https://shop.example.com/.well-known/assetlinks.json. A file at https://example.com/.well-known/assetlinks.json does not automatically cover shop.example.com. Likewise, a redirect from the required URL may prevent verification; serve the file directly at the expected address.

How to check the URL

1. Identify the exact host. Take the hostname from the web links your app is meant to handle, such as www.example.com or links.example.com. Check every host declared for App Links separately.
2. Open the required address. Visit https://HOST/.well-known/assetlinks.json in a browser, replacing HOST with the hostname. The response should display JSON rather than a website page, login screen, error, or redirect.
3. Check the HTTP response when needed. A command such as curl -i https://HOST/.well-known/assetlinks.json shows response headers and content. Look for a successful status, typically 200, and a readable JSON body. Avoid testing only through a browser cache; fetch the live URL.
4. Validate the statement. Confirm that the JSON parses and includes the expected app package and certificate fingerprint, as described below. Check capitalization and punctuation in the fingerprint carefully.
5. Check Android’s verification result. After installing the relevant app build on a device, use Android’s App Links verification tools or the app-link settings available on the device to see whether the host is verified. A reachable file alone does not prove that the installed app matches it.

For example, the URL to check for links on https://www.example.com is https://www.example.com/.well-known/assetlinks.json, not https://www.example.com/.well-known/assetlinks.json/ and not a file under /android/ or /api/.

What must be in the JSON

A typical statement granting an Android app permission to handle links uses the delegate_permission/common.handle_all_urls relation. Its target identifies the Android app through the namespace android_app, the package name, and one or more SHA-256 certificate fingerprints. The structure looks like this:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints": [
      "12:34:56:...:AB:CD"
    ]
  }
}]

This is an illustrative structure, not a usable statement: replace the example package and fingerprint with the real values, and include the complete fingerprint. The JSON must be syntactically valid, including quotation marks, commas, brackets, and matching braces. It should be served as a publicly readable file; it must not require a session, authentication, or a special request header.

Find the right package and fingerprint

The package name in the statement must match the application ID of the app being verified. Do not assume it is the display name or the package name of a different build variant. Check the application’s Android configuration and the actual installed artifact when in doubt.

The SHA-256 value must match the signing certificate for the app delivered to the device. This is a common source of confusion: a locally built debug app, a locally signed release, and a release distributed through an app store can have different signing certificates. If distribution uses a store-managed signing key, the certificate on the delivered app may differ from the upload key. Obtain the appropriate app-signing certificate fingerprint from the distribution setup or inspect the installed/released artifact. You may need to publish multiple fingerprints when users can install legitimate builds signed with different certificates.

Common verification failures

• Wrong hostname: The file exists on the apex domain but not on the subdomain named in the app’s intent filter. Check each host exactly as written.
• Redirects or access restrictions: The URL redirects to another address, returns an access-denied page, or is blocked by a CDN, firewall, or authentication layer. Configure the required path to return the file directly and publicly.
• Invalid JSON: A trailing comma, HTML error page, truncated response, or incorrect data type can make the statement unusable. Validate the body as JSON rather than relying on how a browser formats it.
• Wrong app identity: The package name or signing fingerprint does not match the installed app. Compare against the exact release channel and signing configuration being tested.
• App configuration mismatch: The website file can be correct while the app does not declare the relevant host and web-link intent filters. Review the app’s manifest and its App Links configuration as well as the website.
• Stale verification state: A device may not immediately reflect a newly published statement. Ensure the file is live, then trigger or rerun verification using the supported Android tools for the test environment.

Also distinguish URL verification from link behavior. A verified association lets Android trust the relationship, but the app still needs to handle the incoming URL. A link can be verified and still open the wrong screen—or fail inside the app—if the app’s routing logic does not recognize that path.

Verification URL versus testing tools

The URL is the public location of the association file. Android’s verification tools are separate: they request the file and report whether the device accepts the association for a particular installed app and host. Google’s Digital Asset Links statement checker can also help diagnose whether a published statement can be retrieved and parsed, but it does not replace checking the exact production host, app package, and signing identity you intend to use.

When testing, use a device and app build that reflect the real installation path. A debug build can produce a misleading failure if the website lists only a release fingerprint. Conversely, testing with a debug fingerprint does not establish that the store-distributed app will verify. Keep test and production identities clear, and publish only the statements needed for the app and its legitimate signing certificates.

Frequently Asked Questions

What is the correct Android assetlinks URL?
Use https://YOUR_HOST/.well-known/assetlinks.json. Replace YOUR_HOST with the exact hostname in the App Link, including any subdomain.

Does one assetlinks.json file cover all subdomains?
No. Do not assume a file on the root domain covers its subdomains. Serve a valid statement at the required path on each hostname the app is configured to handle.

Should assetlinks.json return a redirect?
It should be available directly at the required HTTPS URL. A redirect can interfere with Android’s retrieval and verification, so configure the exact URL to return the JSON itself.

Where do I get the SHA-256 fingerprint?
Get it from the signing certificate for the app build users install. For store-distributed apps, distinguish the app-signing certificate from an upload certificate and from a local debug certificate.

Why does the URL open but the App Link remain unverified?
A successful page load only confirms that something is reachable. The JSON, hostname, package name, certificate fingerprint, and app’s declared link configuration must all match, and the device must verify the installed build.

Related

• Insert Roman Numerals in Google Docs and Sheets
• How to Disable Cookies in Chrome, Firefox, Edge and Safari
• Fix Can’t Access Registry Editor in Windows 10