Universal Links & App Links

The model (read this first)

A Universal Link (iOS) / App Link (Android) is a verified two-sided handshake, not a URL scheme:

1. The website hosts a file vouching for the app (apple-app-site-association for iOS, assetlinks.json for Android).
2. The app declares it owns that domain (entitlement / associatedDomains / intentFilter).
3. The OS verifies the pair on install, then one ordinary https URL serves both audiences:
   • App installed → the OS opens the app directly. No redirect, no "Open in app?" prompt.
   • App not installed → the same URL loads the web page (your fallback + install CTA).

You never detect-and-redirect. The OS intercepts the tap. That's the whole point — and why getting the website file exactly right matters more than any app code.

Three decisions before you build

1. Which domain? It must be the terminal host of the shared link — the one that answers 200 with no redirect. A bare-apex → www redirect (or http→https, or a trailing-slash redirect) silently breaks the link. Pick one host and use it in the link, the entitlement, AND where the association file is served. Crucially, the code that generates shared links must emit that terminal host directly — never a host that depends on a redirect. (Keeping the apex→www 301 for humans typing the URL is fine; just don't let a shared link rely on it.)
2. What ID goes in the URL? It must resolve to the same entity on both the web page and the app — this is the most common "it opens but shows the wrong/empty thing" bug. Default: keep the web/SEO-friendly id (slug) in the URL and resolve it to the app's internal id on the app side (a lookup the app likely already has). Only embed the app's internal id directly if the web page can also resolve that id. Either way, add the resolver on whichever side is missing it before you ship.
3. Which paths does the app own? e.g. /item/* — narrow enough that the app doesn't swallow /about or /blog.