Understanding assetlinks.json structure
Minimal valid assetlinks.json
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": ["AA:BB:CC:DD:..."]
}
}
]File Location & Hosting
Must be hosted at: https://yourdomain.com/.well-known/assetlinks.json
- Content-Type: application/json (not text/plain)
- HTTP Status: 200 OK (not 301, 302, or 404)
- Accessibility: Publicly accessible, no authentication required
Key Fields Explained
Must be: "delegate_permission/common.handle_all_urls" for app links
Must be: "android_app" for Android app links
Your app's package name from AndroidManifest.xml (e.g., com.example.app)
Array of SHA-256 fingerprints in uppercase, colon-separated format
Understanding SHA-256 fingerprints
Critical distinction: Play App Signing vs Local Keystore
If you upload unsigned APKs to Google Play Console, Google re-signs your app with a different key. This creates a different SHA-256 fingerprint than your local keystore. Always use the Play Console fingerprint.
How to get SHA-256 fingerprint
Option 1: Google Play Console (Recommended)
- Go to Google Play Console
- Select your app
- Go to Release > Internal testing (or Production)
- Look for "App signing for internal testing" or "Google Play App Signing"
- Copy the SHA-256 certificate fingerprint
- Format: AA:BB:CC:DD:... (uppercase, colon-separated)
Option 2: Using keytool (Local Testing Only)
Only if you self-sign and are not using Play App Signing:
keytool -list -v -keystore keystore.jks | grep SHA256
SHA-256 Format Requirements
- Uppercase: AA:BB:CC (not aa:bb:cc)
- Colon-separated: AA:BB:CC:DD (not AABBCCDD)
- No spaces: AA:BB (not AA: BB)
- In array: ["AA:BB:CC:..."] with square brackets
Multiple Fingerprints
You can add multiple fingerprints if your app is signed with different keys:
"sha256_cert_fingerprints": [ "AA:BB:CC:DD:EE:FF:...", // Release key "11:22:33:44:55:66:...", // Debug key "AA:AA:AA:AA:AA:AA:..." // Other signing key ]
Useful for supporting both debug and release builds, or multiple developer keys.
Common assetlinks.json errors and fixes
SHA-256 fingerprint does not match
Cause: Using local keytool fingerprint when Play App Signing is enabled in Google Play Console
Fix: Get SHA-256 from Google Play Console > App signing section, not from keytool
assetlinks.json not found (404)
Cause: File is not at /.well-known/assetlinks.json or web server not configured
Fix: Verify file location and test with curl. Ensure web server serves from correct root directory.
Package name mismatch
Cause: package_name in assetlinks.json does not match AndroidManifest.xml
Fix: Verify package_name in assetlinks.json exactly matches <manifest package="..."> in AndroidManifest.xml
Content-Type is text/plain
Cause: Web server serving assetlinks.json as plain text instead of JSON
Fix: Configure web server to serve /.well-known/assetlinks.json with Content-Type: application/json
Invalid JSON syntax
Cause: Trailing commas, missing quotes, or mismatched brackets
Fix: Use /assetlinks-validator to check JSON syntax. Remove trailing commas, ensure all keys are quoted.
SHA-256 has lowercase letters
Cause: Fingerprint formatted in lowercase instead of uppercase
Fix: Convert all SHA-256 characters to uppercase: aa:bb:cc → AA:BB:CC
SHA-256 has spaces
Cause: Fingerprint contains spaces instead of being compact
Fix: Remove all spaces: AA: BB: CC → AA:BB:CC
Wrong relation type
Cause: relation field set to something other than delegate_permission/common.handle_all_urls
Fix: Use exactly: "relation": ["delegate_permission/common.handle_all_urls"]
CDN caching assetlinks.json
Cause: Changes to assetlinks.json not reflected because CDN is caching old version
Fix: Purge CDN cache or test with curl. Disable caching for /.well-known/ paths during development.
App signed with different key than assetlinks.json
Cause: App APK signed with key A, but assetlinks.json has fingerprint from key B
Fix: Ensure APK is signed with the same key whose fingerprint is in assetlinks.json
Quick validation with Redirectly
Paste your assetlinks.json and get instant validation with detailed error messages:
Open assetlinks Validator→Frequently asked questions
I have both debug and release builds. What SHA-256 do I use?
Add both to the sha256_cert_fingerprints array. This way both debug and release builds can use app links. Use the release fingerprint for production app links.
Where do I get my package name?
Open AndroidManifest.xml and look for: <manifest package="com.example.app">. The package_name in assetlinks.json must match exactly, including capitalization.
How long does assetlinks.json verification take?
Google Play Console usually verifies within minutes, but can take up to 2 hours. After verification, app links work automatically when app installs from Play Store.
Can I test assetlinks.json locally before deploying?
Yes. Use your local keytool SHA-256 for testing, then swap to the Play Console fingerprint before publishing. Or test on internal testing track in Play Console.
What if my SHA-256 fingerprint changed?
If you changed signing keys, update the sha256_cert_fingerprints array with the new fingerprint. Old fingerprint will stop working. Keep old fingerprints if you need to support old app versions.