React Native deep linking

After this page, your React Native app gets a callback with the path and parameters of every link that opens it, whether the app was closed, in the background, or just installed.

On this page 7
  1. 1. Install the SDK
  2. 2. Create the client once
  3. 3. Let the phone hand links to your app
  4. 4. Check that the SDK sees the link
  5. Or let strait init write the setup
  6. Common errors
  7. Next steps

One prompt · for your AI coding tool

Prompt
Add Strait deep links (and deferred deep links) to this React Native or Expo app.

Read https://straitlink.in/docs/sdks/react-native/ and follow it exactly. If anything here disagrees with that page, the page wins.
My link domain is https://<your-handle>.strait.link and my publishable key is st_pub_live_… (from Dashboard → Setup → Your keys: https://app.straitlink.in/setup#keys).

Rules:
- Use only the publishable key here. Never put a secret key (st_live_…) in app or website code.
- Route every link from the SDK's onLink callback (the event's path and params). Do not add a second deep-link handler for the link domain: with React Navigation, do not also list it in the linking option.
- If this is Expo, it needs a development build (npx expo run:android), not Expo Go. With Expo Router, subscribe in app/_layout.tsx once the root navigation state is ready, and add app/+native-intent.tsx as the docs show.

Steps:
1. Install the SDK with the command on that page.
2. Let the phone open the app: the Android App Links intent filter (autoVerify) for my link domain and my custom scheme, and the iPhone Associated Domain applinks:<your-handle>.strait.link (in Expo: scheme, android.intentFilters and ios.associatedDomains in app.json).
3. Create the client once with publishableKey and endpoint, call start() once at launch, and subscribe to onLink.
4. Map link paths to screens in this codebase.

Finish by telling me exactly how to check it:
- curl https://<your-handle>.strait.link/.well-known/assetlinks.json and /.well-known/apple-app-site-association list my app
- adb shell pm get-app-links <package> says verified after a fresh install
- a tap from WhatsApp on a real phone opens the right screen and onLink fires with matched: true

The full prompt, and the others

By hand · the install line

Terminal
npm install @straitlink/react-native@0.11.6

Then follow the steps below

Time
About 10 minutes
You need
React Native 0.72 or newer, a workspace with your app in Dashboard → Apps & stores
Works on
Android, iPhone

Using Expo? Follow Expo (Expo Router) instead: the setup is the same, but the native settings go in app.json.

1. Install the SDK

The SDK installs from npm, pinned to a version, together with the two packages it needs:

Terminal
npm install @straitlink/react-native@0.11.6 @react-native-async-storage/async-storage react-native-play-install-referrer

AsyncStorage keeps the once-per-install flag and any open reports that couldn't be sent yet. The Play Install Referrer module gives Android installs an exact match.

You should see: @straitlink/react-native in your package.json dependencies.

2. Create the client once

Create it outside your components and start it when the app launches:

links.ts (@straitlink/react-native 0.11.6)
import AsyncStorage from '@react-native-async-storage/async-storage';
import { PlayInstallReferrer } from 'react-native-play-install-referrer';
import { createStrait, fromPlayInstallReferrer } from '@straitlink/react-native';

export const links = createStrait({
  publishableKey: 'st_pub_live_…',        // Dashboard → Setup → Your keys (safe in apps; never the secret key)
  endpoint: 'https://hilltop.strait.link',     // your Strait link host
  storage: AsyncStorage,            // required for reliable analytics
  installReferrer: fromPlayInstallReferrer(PlayInstallReferrer),
});

links.start();

Import ./links once from index.js. endpoint is your workspace's link domain: the SDK sends its requests there and treats links on that host as yours. Call start() once. onLink replays past events to late subscribers, so your navigator can subscribe after start() without missing the launch link.

You should see: the app starts as before after a rebuild (npx react-native run-android), because the SDK adds a native module.

Android: one intent filter for verified links on your domain, one for your custom scheme (used when a browser hands a link to your app):

android/app/src/main/AndroidManifest.xml
<activity android:name=".MainActivity" android:launchMode="singleTask" android:exported="true">
  <!-- Verified links: https://hilltop.strait.link/… opens the app directly -->
  <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" android:host="hilltop.strait.link" />
  </intent-filter>
  <!-- Browser hand-off: yourapp://shop.example.com/product/42 -->
  <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="yourapp" />
  </intent-filter>
</activity>

iPhone: in Xcode, add Associated Domains with applinks:hilltop.strait.link, and your scheme under Info → URL Types.

The verified-link half also needs your SHA-256 fingerprints and Team ID in Apps & stores; that's step 1 of the go-live checklist.

You should see: after a rebuild, this command opens your app:

Terminal
adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42"

Add a temporary log next to start():

links.ts
links.onLink((e) => console.log('Strait link:', e.kind, e.route, e.matched, e.path));

Run the adb command from step 3 again.

You should see: Metro logs Strait link: direct custom_scheme true /product/42. Then tap a real link from Messages or Gmail: route becomes custom_scheme (browser hand-off) or app_link (verified link).

Or let strait init write the setup

From your app's folder:

Terminal
npx @straitlink/cli init --key st_pub_live_… --host hilltop.strait.link

It writes links.ts (step 2) with your key, host and an onLink log, and prints the install command, the intent filters for step 3, the iPhone Associated Domains entry and the Settings fields, each filled in. Steps your project already has are marked [already done]. It never edits your existing files.

Common errors

  • Native module ... is null or PlayInstallReferrer is undefined. The app wasn't rebuilt after npm install. Native modules need a new build, not just a Metro reload.
  • The adb command opens a chooser or another app. Another installed app also claims the scheme. Pick a more specific one, like hilltopshoes.
  • The callback never fires. links.ts is not imported at startup, so start() never runs.

Next steps

  • Receive links: send e.path to the right screen with React Navigation.
  • Test: deep links, deferred links and analytics on a real phone.