AnilBurcu Deep links that open the app every time
Two layers, different jobs
- Custom schemes (
myapp://...): trivial to set up, work from inside your own emails and QR flows, but any app can claim a scheme and browsers treat them as second-class. Fallback layer. - Universal links (iOS) / App links (Android) (
https://yourdomain.com/...): the real thing. They need server-side proof files and that is where every setup fails.
Ship both: schemes for internal redirects (OAuth return, payment return), https links for anything a user might tap outside the app.
iOS: the AASA file and Apple's CDN
The proof file lives at https://yourdomain.com/.well-known/apple-app-site-association: HTTPS, no redirects, JSON body, appID as TEAMID.bundleid. The entitlement side is applinks:yourdomain.com (Expo: associatedDomains in app config).
The part that costs people days: devices do not fetch your file directly. Apple's CDN fetches it (first pickup within about a day) and caches it, so an AASA fix is not live when your server says it is. For development there is an alternate mode: entitlement applinks:yourdomain.com?mode=developer plus the device's developer mode skips the CDN. Use it for iteration, remove it for release builds.
If links still open Safari instead of the app: long-press the link and check for the "Open in app" option, confirm the file is reachable with curl -i (status 200, no redirect chain), and remember that pasting a URL into Safari's address bar deliberately does NOT trigger universal links; tap one from Notes or Messages instead.
Android: assetlinks.json and the signing key trap
The proof file lives at https://yourdomain.com/.well-known/assetlinks.json with the app's package name and the SHA-256 fingerprint of the certificate that signs what ships. The trap: with Play App Signing (the norm), Google re-signs your app, so the fingerprint must come from Play Console's App integrity page (the app signing key), NOT from your upload key or local keystore. A local-keystore fingerprint makes verification fail silently and only in production, which is the worst combination.
Add fingerprints additively: dev builds and store builds can both live in the file. Intent filters need android:autoVerify="true" on the https filter. Check verification state on a device with:
adb shell pm get-app-links your.package.name
verified next to the domain is the goal; anything else names the failing domain.
Cold start vs warm start, the classic lost link
A link that launches the app arrives through the initial-URL path; a link tapped while the app runs arrives through the URL event. Handling only the event listener means cold-start links vanish, and that is the most common deep-link bug report. expo-router handles both when the scheme and domains are configured, but anything custom (auth guards, splash gates, onboarding redirects) must re-apply the pending link AFTER the gate resolves, or the user lands on the home screen and the link dies.
Test both paths explicitly: once with the app killed, once with it backgrounded.
Testing without a website deploy
# custom scheme, both platforms
npx uri-scheme open "myapp://lesson/42" --ios
npx uri-scheme open "myapp://lesson/42" --android
# https links on Android without waiting for verification
adb shell am start -a android.intent.action.VIEW -d "https://yourdomain.com/lesson/42" your.package.name
iOS https links cannot be faked from the terminal in the same way; that is what mode=developer exists for.
Adjacent traps
- OAuth and payment providers redirect back via your scheme or https link; a changed scheme breaks sign-in in the field, so treat the scheme as API surface and never rename it casually.
- Deferred deep links (install, then first open lands on content) are not a platform feature; they require an attribution/linking service. Do not promise the product team otherwise.
- Every route a link can open must handle "referenced thing is gone" gracefully; links outlive content.