Home / Developer notes
Developer notes
For engineers setting up universal links and Android App Links. Marketers can skip this section.
Guides
Setup guides
iOS
The apple-app-site-association file explainedHow the apple-app-site-association file works, where to host it, its JSON structure, app IDs, components rules and how to test universal links with swcutil.Android
Android App Links setup, step by stepSet up Android App Links end to end. Add an autoVerify intent filter, host assetlinks.json with the right fingerprint and verify each domain with adb.Android
The assetlinks.json file explainedHow assetlinks.json works for Android App Links, where to host it, the statement format, package names, SHA-256 fingerprints and how to verify links with adb.Both
Deferred deep linking, how it works after installDeferred deep linking sends new users to the right screen after install. Why universal links and App Links stop at install and how Install Referrer helps.Both
In-app browsers and deep links, what to doWhy deep links tapped in Instagram, Facebook, TikTok and LinkedIn often stay on the web, which mitigation patterns help, and how to test in each in-app browser.iOS
Universal links setup, step by step for iOSSet up iOS universal links end to end. Add the Associated Domains entitlement, host the AASA file, handle the link in your app and test it on a real device.
Errors
Why deep links fail
Android
App Links fail on Play installs, wrong fingerprintassetlinks.json lists the upload or debug key fingerprint, not the Play App Signing key that signs the app users install.Android
App Links open the browser, autoVerify missingThe intent filter lacks android autoVerify true, the BROWSABLE category, or the http and https data schemes.Android
One App Links host fails verificationOne host in the manifest has no valid assetlinks.json, such as a staging, VPN-only or extra subdomain.Android
assetlinks.json has the wrong package nameThe package_name in assetlinks.json does not match the application ID of the installed app.Android
assetlinks.json has the wrong structureThe file is not an array of statements, or a statement is missing target fields such as namespace android_app.Android
assetlinks.json is missing handle_all_urlsThe relation array does not include delegate_permission/common.handle_all_urls, which is the relation App Links check for.Android
assetlinks.json is not valid JSONThe assetlinks.json file has a syntax error, so Android reads it as an empty statement list.Android
assetlinks.json redirects or has the wrong typeThe file is served through a 301 or 302, returns a status other than 200, or is not sent as application/json.Both
Links open the website inside Instagram or TikTokThe in-app browser decides whether to hand links to other apps, and many are widely reported to keep links in their own web view.Both
New users land on the home screen after installUniversal links and App Links only route to an installed app, so the link is lost on the way through the App Store or Play Store.iOS
AASA app ID does not match the appThe app ID in the file does not match the app, usually a wrong Team ID prefix, a typo in the bundle ID, or a missing prefix.iOS
AASA entry has no paths or componentsThe details entry has an empty or missing components or paths array, so it claims no URLs.iOS
AASA file has no applinks sectionThe apple-app-site-association file only has webcredentials or appclips keys and no applinks key.iOS
AASA file has the wrong structureThe keys are not where iOS expects them, for example a top-level array, a missing details array, or mixed legacy and current formats.iOS
AASA file is behind a redirect or blockedThe file is served through a redirect, or a firewall, bot rule or geo block stops Apple's CDN from fetching it.iOS
AASA file is larger than 128 KBApple's archived documentation sets a 128 KB uncompressed limit for the file, and a long list of paths can exceed it.iOS
AASA file is not valid JSONThe apple-app-site-association file contains a syntax error, so it cannot be parsed as JSON.iOS
AASA changes are not picked up on devicesApple's CDN caches the file and devices only check for updates roughly once a week after install.iOS
AASA file served with the wrong content typeThe server sends the file as something other than JSON, such as an HTML page, a download, or a signed pkcs7 file.iOS
Links on your own website stay in SafariNavigation within the same domain is treated as continuing in the browser, so iOS does not open the app.iOS
Some URLs open the app and others do notThe URL is not covered by any components rule, an earlier exclude rule wins, or the case does not match.iOS
Universal link opens Safari when typed or pastediOS never treats direct navigation in the address bar as a universal link, by design.