Platform mechanics
Two mechanisms, two failure modes.
Apple’s Universal Links and Android’s App Links do the same job and fail differently. Knowing which one you are looking at is most of the debugging.
The same idea
Both let an https:// address open an app instead of a web page, without a custom scheme like myapp:// and without the person tapping needing to know anything. Both work by the operating system fetching a file from your domain and checking that the domain vouches for the app.
That is where the similarity ends, and the differences are what produce the two quite distinct kinds of “my link does nothing”.
How each one verifies
| iOS — Universal Links | Android — App Links | |
|---|---|---|
| The file | /.well-known/apple-app-site-association | /.well-known/assetlinks.json |
| What identifies the app | Team ID and bundle identifier | Package name and signing certificate fingerprints |
| When it is fetched | At install, and cached aggressively | At install, and re-verified by the system |
| If verification fails | Silently opens Safari. No error anywhere. | Opens the browser, and adb can tell you why |
The failure you are probably looking at
On iOS, the cache. The association file is fetched around install time and not re-fetched because you changed it. A correct file published after the app was installed does not fix the app already on your phone — delete and reinstall it. More time is lost to this single fact than to everything else on this page.
On Android, the fingerprints. There is rarely one. A debug build, a Play-signed release and an internal test track can all differ, and a file listing only one of them works in exactly one of those situations. Ours takes a list for that reason — Android setup explains why it is plural.
On both, the in-app browser. A link tapped inside Instagram, TikTok or a QR scanner’s built-in browser may never reach the operating system at all, so neither mechanism gets a chance to run. That one is its own page because it is the most common of the three and the least documented.
What we do about it
We serve both files for your link host, from the values you enter once, so the two formats and their differences are not yours to keep straight. The setup pages are iOS and Android, and the quickstart covers the SDK side once for every platform.