React Native Deep Linking Guide: Universal Links, App Links, Routing, and Release Testing
deep linkingUniversal LinksApp LinksExpoReact Navigationroutingmobile QA

React Native Deep Linking Guide: Universal Links, App Links, Routing, and Release Testing

RReact Native Store Editorial Team
2026-11-20
6 min read

Plan, configure, and test React Native deep links across Universal Links, App Links, Expo Router, React Navigation, and authentication states.

React Native deep linking connects a web URL or custom scheme to a precise screen inside your app. This guide provides a repeatable way to plan routes, configure iOS Universal Links and Android App Links, support Expo Router or React Navigation, protect authentication flows, and verify links before release.

Overview

A deep link is an address that opens a specific location in an app rather than stopping at the home screen. A product link might open a product detail screen, while an invitation link could open an acceptance flow with a token or referral code.

React Native projects commonly support three link types:

  • Custom URL schemes: Addresses such as myapp://orders/42. They are useful for development, app-to-app communication, and fallback handling, but another installed app could potentially register the same scheme.
  • iOS Universal Links: Standard HTTPS URLs associated with an iOS app and a domain you control.
  • Android App Links: Standard HTTPS URLs associated with an Android app through domain verification.

Use HTTPS links as the primary production experience when your app needs shareable campaign, content, account, or commerce URLs. Keep a custom scheme available when it supports a specific integration or local testing workflow. The navigation layer still matters: Expo Router maps URLs to its file-based route structure, while React Navigation requires an explicit linking configuration that maps paths to navigators and screens.

Deep linking is not only a routing task. It crosses the app binary, operating system, domain configuration, authentication state, analytics, and release process. A link can be correctly formatted and still open the browser, show the wrong screen, lose its parameters, or fail when the app was terminated.

How to estimate

Before implementation, estimate deep-linking effort by counting link families and states rather than counting URLs alone. A small app with three routes may require more work than a larger app if links must handle login, expired tokens, redirects, and multiple domains.

Use this repeatable estimate:

  1. Count link families. Group URLs by behavior, such as content, invitations, password recovery, checkout, and marketing campaigns.
  2. Count app states. For every family, test a cold start, a warm or background start, an already-open app, a logged-out user, an authenticated user, and an expired or malformed parameter.
  3. Count platform paths. Include iOS Universal Links, Android App Links, custom schemes, and web fallback behavior where applicable.
  4. Add environment coverage. Separate development, staging, and production domains. Association files and signing identifiers must match the intended build.
  5. Reserve release validation. Add time for TestFlight or equivalent iOS distribution, an Android release-like build, real-device checks, analytics verification, and rollback planning.

A useful planning formula is:

test cases = link families × app states × platforms × environments

This is a planning model, not a guarantee of engineering hours. Reduce the matrix by grouping equivalent routes, but do not remove states that change authentication, data safety, or navigation behavior.

Inputs and assumptions

URL and route inventory template

Maintain a small inventory in the repository or product documentation. It should be reviewed whenever routes or authentication rules change.

URL patternApp destinationRequired stateFallbackOwner
https://example.com/products/:idProduct detailOptional loginWeb product pageCommerce
https://example.com/invite/:tokenInvite acceptanceLogin or signupWeb invite pageAccounts
myapp://settingsSettingsAuthenticatedSign-in screenMobile

Association-file checklist

  • Serve the iOS association file from the expected well-known path over HTTPS, without relying on a redirect.
  • Confirm the iOS app identifier, team or signing identity, and permitted paths match the build being tested.
  • Serve the Android Digital Asset Links file from its expected well-known path.
  • Confirm the Android package name and signing certificate fingerprint match the installed or released build.
  • Check content type, accessibility, certificate validity, and whether a CDN or proxy is altering the response.
  • Use separate domains or clearly separated paths for staging when production association data must not authorize a staging app.

Do not treat an association file as a substitute for route handling. The operating system decides whether a URL can open the app; Expo Router, React Navigation, or another navigation layer decides where the app goes next.

Authentication assumptions

Never assume a link recipient is already signed in. Parse and validate the URL first, then store only the minimum pending destination or one-time value needed to continue after authentication. After login, resume the intended route through a controlled allowlist. Avoid forwarding arbitrary paths or query parameters into privileged screens.

Worked examples

Cold-start workflow

  1. Terminate the app completely.
  2. Open an HTTPS Universal Link or App Link from a device browser or test command.
  3. Confirm the operating system opens the app and that the initial URL is available to the JavaScript layer.
  4. Verify the route, decoded parameters, loading state, and error state.
  5. Repeat with the app installed from a release-like build, not only a development client.

For custom schemes, use the relevant simulator or device URL-opening command. On Android, an adb intent can exercise a URL; on Apple simulators, xcrun simctl openurl can open one. Command syntax and behavior can vary by platform tooling, so keep the exact commands in the project’s QA notes and verify them after toolchain updates.

Background and warm-start workflow

Open the app normally, place it in the background, and trigger a different link. Then repeat while the app is already visible. Confirm that the new URL is handled once, rather than being processed both by initial-link logic and an event listener. Add duplicate-event protection if the navigation library or platform lifecycle can deliver the same intent through more than one path.

Logged-out and redirect workflow

Open an authenticated destination while logged out. The app should show the correct sign-in or signup screen, retain a safe pending destination, and resume only after successful authentication. Test cancellation, expired sessions, expired invitation tokens, malformed IDs, and a user who lacks permission. A permissions guide and a payments guide may also be useful when deep links lead into protected device or purchase flows: React Native Permissions Guide and React Native Payments and In-App Purchases.

With React Navigation, define prefixes for the HTTPS domain and custom scheme, then map each path to a known screen. With Expo Router, treat the file and folder structure as part of the public URL contract. In either approach, document parameter types, optional segments, query-string behavior, and the fallback screen. Renaming a route can be a breaking change for links already printed in emails, advertisements, support articles, or QR codes.

When to recalculate

Revisit the link inventory and test matrix whenever you add a campaign URL, change route structure, introduce a new authentication step, switch between Expo Router and React Navigation, change application identifiers, rotate signing credentials, add a domain, or alter web fallback behavior.

Recalculate before each app submission and after major React Native, Expo, navigation-library, or mobile operating-system updates. Also repeat production validation when association files, CDN rules, certificates, redirects, or release channels change. Domain verification may behave differently between a development build, an internal distribution build, and a store-installed build, so test the artifact users will receive.

For the final release check, record the exact app version, build type, domain, device, operating-system version, URL, expected destination, actual destination, and result. Add a regression test for every previously fixed failure. Connect failures to crash reporting or monitoring so broken links can be triaged by app version and route; the React Native Crash Reporting and Monitoring Tools guide covers that broader workflow. Treat deep links as an integration surface, not a one-time configuration task: maintain the inventory, validate association files, and run the smallest complete matrix before every meaningful release.

Related Topics

#deep linking#Universal Links#App Links#Expo#React Navigation#routing#mobile QA
R

React Native Store Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.