Installation

Detour provides a React Native SDK (@swmansion/react-native-detour) compatible with Expo and bare React Native projects.

AI agent skills

Detour ships two AI coding-agent skills: detour-onboarding for a setup from scratch, and migrate-to-detour for moving off Branch or AppsFlyer. Both cover this page. See Detour Skills.

A Detour app in the Dashboard is required before the SDK can resolve links. See Getting Started.

Install package

npm

npm install @swmansion/react-native-detour

yarn

yarn add @swmansion/react-native-detour

pnpm

pnpm add @swmansion/react-native-detour

bun

bun add @swmansion/react-native-detour

Peer dependencies (Expo)

For Expo projects (including prebuild), install peer dependencies with Expo CLI so versions are matched to your Expo SDK:

npx expo install expo-application expo-clipboard expo-constants expo-localization @react-native-async-storage/async-storage

Bare React Native projects

If you are not using Expo CLI, install peer dependencies with your package manager and pin versions compatible with your React Native/Expo Modules setup.

npm

npm install expo-application expo-clipboard expo-constants expo-localization @react-native-async-storage/async-storage

yarn

yarn add expo-application expo-clipboard expo-constants expo-localization @react-native-async-storage/async-storage

pnpm

pnpm add expo-application expo-clipboard expo-constants expo-localization @react-native-async-storage/async-storage

bun

bun add expo-application expo-clipboard expo-constants expo-localization @react-native-async-storage/async-storage

Async Storage is optional

Skip @react-native-async-storage/async-storage if you pass a custom storage adapter in config.storage. See Custom Storage.

Expo Modules setup (React Native CLI)

Four of the peer dependencies above are Expo Modules:

• expo-application
• expo-clipboard
• expo-constants
• expo-localization

They ship native code that has to be autolinked into your android/ and ios/ projects. An Expo project does this for you. A bare React Native CLI project needs Expo Modules added once:

npx install-expo-modules@latest

This sets up Expo Modules autolinking (and on iOS raises the deployment target to the Expo Modules minimum).

install-expo-modules also switches the native JS bundling step to Expo CLI (export:embed). That requires metro.config.js to extend expo/metro-config, which is a superset of @react-native/metro-config and safe in bare projects. The tool usually migrates the file for you, but verify it, especially if you had customized it:

metro.config.js

const { getDefaultConfig } = require("expo/metro-config");
const { mergeConfig } = require("@react-native/metro-config");

module.exports = mergeConfig(getDefaultConfig(__dirname), {});

Then align the Expo package versions to your setup:

npx expo install --fix

Build errors after adding Expo Modules

If the app throws at startup or a release build fails after adding Expo Modules, see bare React Native CLI build issues.

Device info provider

Deferred-link matching builds a probabilistic fingerprint of the device. The SDK reads three values for it:

• device model
• manufacturer
• OS version

Those values come from a device info library. Install one of the two supported ones. Both are optional peer dependencies, and the SDK uses whichever it finds:

expo-device (recommended for Expo)

npx expo install expo-device

react-native-device-info

npm install react-native-device-info

Which one to pick

Choose react-native-device-info if your project already depends on it. Otherwise expo-device is the simplest option for Expo apps.

The device info source is not configurable. Unlike storage, it has no adapter. The SDK detects the installed library at import time and prefers expo-device when both are present.

One of the two is required

Install neither and the SDK throws while building the fingerprint:

[react-native-detour] No device info library found. Install either "expo-device" or "react-native-device-info".

Deferred-link matching then fails and Universal/App Link clicks are not recorded. Link navigation itself keeps working, because the SDK fails open.

Native link configuration

Installing the package does not register incoming links with iOS or Android.

Expo

Copy the generated ios.associatedDomains and android.intentFilters values from App configuration in the Dashboard into app.json, app.config.js, or app.config.ts:

app.json

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:<your-host>"]
    },
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "<your-host>",
              "pathPrefix": "/<app-hash>"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

Use the exact Dashboard output: it also contains any required legacy short-link prefixes. New short links reuse /<app-hash> and do not require another native build.

If your app is served from a custom domain, the Dashboard generates both values for that domain. Assign the domain before you copy them. Changing the host an app is assigned to later needs a new build. Do not add hosts it did not generate: on Android 11 and lower that breaks App Link verification for every host at once, see Verification.

The same host belongs in the handler’s hosts list, which is separate from the native configuration.

Custom schemes are optional and are not generated by the Dashboard. If you use links such as myapp://product/42, add the scheme separately:

app.json

{
  "expo": {
    "scheme": "myapp"
  }
}

These are build-time settings. After changing the app config, create a new native build. In a Continuous Native Generation workflow, regenerate the native projects with npx expo prebuild --clean, then run npx expo run:ios or npx expo run:android. Alternatively, create a new EAS development build. Reloading Metro or publishing an OTA update does not apply native configuration changes.

Expo Go cannot test the complete flow

Expo Go cannot register your app’s Associated Domains, intent filters, or custom scheme, and it does not represent an installation of your app. It can still be useful for JavaScript-only navigation work, but use a development build to test Universal/App Links and a real device to test the complete deferred-link flow.

Bare React Native

iOS Universal Links

In Xcode, open your app target, select Signing & Capabilities, add the Associated Domains capability, and enter applinks:<your-host>. The resulting entitlements entry is:

<App>.entitlements

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:<your-host></string>
</array>

Android App Links

Paste the generated Dashboard filter into the MainActivity declaration in AndroidManifest.xml:

AndroidManifest.xml

<activity
  android:name=".MainActivity"
  android:exported="true">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" />
    <data android:host="<your-host>" />
    <data android:pathPrefix="/<app-hash>" />
    <!-- The Dashboard adds any required legacy short-link prefixes. -->
  </intent-filter>
</activity>

Use the exact host and paths generated for your app.

Custom-scheme links (optional)

The Dashboard does not generate custom-scheme registration. If you use scheme links, add CFBundleURLTypes to the iOS Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Add a separate filter to the Android MainActivity:

AndroidManifest.xml

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="myapp" />
</intent-filter>

iOS callback forwarding

DetourProvider reads cold-start and runtime URLs through React Native’s Linking API. Verify that your AppDelegate forwards Universal Link and custom-scheme callbacks to RCTLinkingManager.

The snippets below are for an AppDelegate that does not already provide this forwarding. If its superclass or another integration handles links, preserve that behavior and merge the handlers instead of adding duplicate forwarding or replacing the existing implementation.

Swift

import React

func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
  return RCTLinkingManager.application(
    application,
    continue: userActivity,
    restorationHandler: restorationHandler
  )
}

func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}

Objective-C++

#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application
  continueUserActivity:(nonnull NSUserActivity *)userActivity
  restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
  return [RCTLinkingManager application:application
                  continueUserActivity:userActivity
                    restorationHandler:restorationHandler];
}

- (BOOL)application:(UIApplication *)application
  openURL:(NSURL *)url
  options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}

Android callback delivery

With the standard MainActivity : ReactActivity, no Detour-specific callback is required. React Native reads the cold-start VIEW intent from the activity and forwards later onNewIntent calls to Linking.

Set android:launchMode="singleTask" when links should be delivered to the existing MainActivity instance. React Native then emits the runtime url event consumed by DetourProvider. If you use a custom activity that does not inherit React Native’s default intent handling, you must forward its intents to React Native yourself.

Credentials

Both values come from API configuration in the Dashboard: the appID and the publishable apiKey. See Getting Started.

import { type Config } from '@swmansion/react-native-detour';

export const detourConfig: Config = {
  apiKey: process.env.EXPO_PUBLIC_DETOUR_API_KEY!,
  appID: process.env.EXPO_PUBLIC_DETOUR_APP_ID!,
  shouldUseClipboard: true,
};

Keep apiKey and appID in environment variables or another secure configuration layer.

Next steps

1. Implement the provider and link handling in Usage.
2. Pick a runnable app pattern in Examples.
3. Verify the native link configuration in Testing.
4. Fill in the store declarations from Privacy before you submit a build.
5. If upgrading existing code, follow Migration to v2 and start from From 0.x or From 1.0.1.