Deep links work perfectly in development, where the app is installed, running and logged in. In production none of those hold. The three failure modes are predictable and each one silently sends users to a home screen instead of the thing they tapped, which reads as a marketing failure rather than an engineering one.
01Cold start is a race
When a link opens an app that is not running, the link arrives before your navigation stack, authentication state or data layer are ready. Handling it immediately means navigating to a screen that cannot render; ignoring it means dropping the link.
The fix is to capture the incoming link and hold it until the app declares itself ready, then resolve it. That readiness usually means auth state is known - not merely that the UI mounted.
Test this specifically by force-quitting the app before tapping the link. Testing with the app already running exercises a completely different path and is the reason this bug reaches production so often.
02The three cases you must handle
Each is a different user situation and needs a different outcome.
| Scenario | What should happen | Common failure |
|---|---|---|
| App running | Navigate directly | Works; the only case usually tested |
| App installed, not running | Capture, wait for ready, then navigate | Link dropped, user lands on home |
| App not installed | Send to store, restore intent after install | Intent lost; user installs and sees nothing |
| Installed, not authenticated | Hold intent, authenticate, then navigate | User logs in and is dumped on home |
| Content unavailable | Explain, offer nearest useful screen | Blank screen or crash |
03Deferred links and their limits
Restoring intent through an install requires attribution infrastructure, because the store round trip loses your context. Vendor SDKs solve this with fingerprinting or platform mechanisms, with real reliability limits.
Set expectations accordingly. Deferred deep linking is best-effort and platform privacy changes have made it less reliable over time. Design the post-install experience so it is good without the deferred link and better with it, rather than depending on it.
For high-value flows, a short code the user can enter is unglamorous and works every time. It is often the right answer for onboarding into a specific workspace or event.
04Getting the platform configuration right
Universal links and app links both require server-side association files served correctly - right path, right content type, no redirect. Misconfiguration causes the link to open in a browser instead of the app, which looks like a code bug and is not.
These files are also cached by the platforms, so changes do not take effect immediately and testing gives misleading results after edits. Verify with the platform validation tools rather than by tapping links and inferring.
Keep the web fallback genuinely useful. Every deep link will sometimes open in a browser, and a page that says 'open in app' with no content is a dead end for anyone who cannot.
Topics
Aarav Patel
Principal Engineer · SyncTrix
Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.
Building something like this?
SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.
Talk to an engineer