Deep linking connects a URL to a specific React Native screen, whether the link comes from a website, email, push notification, or OAuth provider. This guide explains how to design that flow, configure Expo or React Navigation, verify Android App Links and iOS Universal Links, handle cold starts and background resumes, and estimate the testing effort before release.
Overview
A reliable deep-linking implementation has four cooperating layers:
- Entry point: A user taps a web URL, notification action, email link, or authentication callback.
- Operating system: Android or iOS decides whether the installed application is associated with that URL.
- React Native runtime: Expo or the native linking configuration receives the URL when the app is launched or resumed.
- Navigation and application state: The app maps the URL to a route, loads required data, and handles authentication or invalid parameters.
The flow can be represented as:
URL tap
|
v
OS domain verification
|--------------------|
| |
installed app no verified app
| |
v v
React Native link browser or fallback
|
v
route parser -> auth check -> screen/data load
Use HTTPS URLs as the primary public interface when you need links to work from browsers, email, and web content. Custom schemes can still be useful for development or selected OAuth configurations, but they do not provide the same domain-verification behavior as Universal Links and App Links.
Keep URL parsing separate from screen components. A central link policy should decide which paths are public, which require a session, how identifiers are validated, and what happens when a route is unknown. This makes behavior consistent across push notifications, email links, and authentication redirects.
How to estimate
Deep-linking effort is easier to estimate by counting behaviors rather than screens alone. Create one row for every link scenario and score its complexity using three inputs:
- Platforms: Android, iOS, or both.
- Lifecycle states: app closed, app in the background, or app already active.
- Application conditions: signed out, signed in, missing data, invalid URL, or unavailable network.
A simple planning score is:
Scenario score = platform count × lifecycle count × condition count
This is not a delivery-time formula. It is a repeatable way to expose test coverage. A public product link that opens one screen might have a low score. An OAuth callback that must resume after a browser handoff, restore navigation state, wait for session initialization, and handle cancellation has a higher score even if it ultimately opens the same screen.
For each scenario, record:
- The source of the URL, such as email, notification, website, or OAuth provider.
- The expected route and required parameters.
- Whether the app must be installed for the intended behavior.
- The expected fallback when the route cannot be opened.
- Whether analytics, attribution, or security review is required.
Estimate implementation work separately from verification work. Native association files, entitlements, intent filters, navigation mapping, authentication coordination, and device testing are distinct tasks. This separation prevents a configuration change from being treated as complete merely because a development build opens a URL.
Inputs and assumptions
Choose a URL contract
Define stable paths before writing navigation code. For example:
https://example.com/products/42
https://example.com/orders/8f3c
https://example.com/auth/callback
Map paths to semantic destinations rather than copying URL strings throughout the app. A route such as /products/:id should validate the identifier, load the product, and show a deliberate not-found state. Query parameters should be treated as untrusted input and parsed defensively.
Expo and React Navigation configuration
Expo projects can use the app configuration and linking support provided by Expo, while Expo Router derives much of its route structure from the file system. React Navigation projects typically define a linking configuration containing URL prefixes and a screen-to-path map. The concepts are the same: declare accepted prefixes, map nested routes, and provide a fallback for unknown paths.
For a React Navigation-style configuration, the shape may look like this:
const linking = {
prefixes: ['https://example.com', 'myapp://'],
config: {
screens: {
Home: '',
Product: 'products/:id',
Orders: {
screens: {
Detail: 'orders/:orderId'
}
}
}
}
};
Treat this as an architectural example, not a drop-in configuration. Names must match your navigator hierarchy, and the exact Expo or navigation APIs should be checked against the versions used by the project.
Platform association requirements
Android App Links require an intent filter for the relevant HTTPS host and a domain association file served from the host. iOS Universal Links require the associated-domains entitlement and an Apple association file served from the expected well-known location. Confirm the exact file format, content type, redirects, path rules, signing details, and entitlement settings in the current platform documentation and your build configuration.
Test the association files on the real production-like domain, not only on a local development server. A valid file that is inaccessible because of a redirect, certificate issue, content-type problem, or incorrect path rule can make the app appear to have a navigation bug when the OS never delivered the URL.
Authentication assumptions
Authentication redirects need a dedicated state machine. On receipt of a callback, first validate the expected scheme, host, path, and state or code parameters. Then coordinate with session initialization before navigating to a protected screen. If the user is signed out, preserve the intended destination in controlled application state rather than trusting an arbitrary return URL.
Deep links are not a replacement for authorization. A link containing an object identifier should still be checked against the current session. Review token storage and session renewal alongside this work using the React Native Authentication Patterns guide.
Worked examples
Example 1: A public product link
Suppose an email contains https://example.com/products/42. The route is public, so the app can parse the identifier immediately, display a loading state, and fetch the product. Test the URL when the app is installed and closed, installed and backgrounded, and already open. Also test an unknown product, a malformed identifier, no network connection, and a signed-out user.
If the app is not installed, the browser should receive a useful web representation or fallback page. Do not assume that every web URL can install or open the application automatically.
Example 2: A protected order link from a notification
A notification tap might open https://example.com/orders/8f3c. The notification handler should pass the URL into the same central link resolver used for email and web links. If session restoration is still running, queue the destination instead of attempting navigation before the root navigator exists. After authentication completes, navigate once and clear the pending destination to prevent duplicate opens.
This coordination is also relevant to notification permissions, payload design, and background behavior; compare the implementation with the React Native Push Notifications guide.
Example 3: An OAuth callback
An OAuth provider may return to a custom scheme or an HTTPS callback, depending on the provider and platform setup. Test approval, cancellation, an expired authorization attempt, a missing state value, and a callback received while the app is already running. The callback screen should not blindly navigate based on a URL parameter. It should validate the response, exchange the code through the approved flow, update session state, and then return the user to a known destination.
A practical test matrix looks like this:
| Scenario | Expected result |
|---|---|
| Verified domain, app installed | Correct native route opens |
| App closed | Initial URL is processed after navigation is ready |
| App in background | Existing navigation state is updated once |
| App not installed | Browser or controlled fallback opens |
| Invalid route or identifier | Safe not-found or fallback screen appears |
| Signed-out protected route | Login appears and destination is restored safely |
| Unverified domain | Behavior is documented and does not look like a successful app link |
When to recalculate
Revisit the deep-linking estimate whenever the inputs change, not only when a release is blocked. Recalculate after adding a route, introducing a new navigator, changing a domain, modifying association-file paths, switching authentication providers, changing notification payloads, or altering session restoration.
Repeat the platform matrix after upgrading Expo, React Native, React Navigation, or native build tooling. Operating-system behavior, entitlements, intent handling, and association-file requirements can change independently of JavaScript code. Also retest when a domain certificate, redirect policy, CDN, or hosting configuration changes.
Before release, turn the estimate into a checklist: list every URL pattern, multiply it across lifecycle states and authentication conditions, then assign an expected result. Run the highest-risk cases on physical Android and iOS devices, inspect the native logs when the OS does not deliver a link, and confirm that invalid links fail safely. Pair this work with the React Native Testing Strategy guide and your CI workflow so route parsing is covered automatically while OS-level association behavior remains part of device testing.