# 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.

- 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

Source: https://straitlink.in/docs/sdks/react-native/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

Using Expo? Follow [Expo (Expo Router)](https://straitlink.in/docs/sdks/expo/) 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:

```bash
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:

```ts title="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.

## 3. Let the phone hand links to your app

**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):

```xml title="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](https://straitlink.in/docs/production-checklist/).

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

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

## 4. Check that the SDK sees the link

Add a temporary log next to `start()`:

```ts title="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:

```bash
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](https://straitlink.in/docs/sdks/react-native/receive-links/): send `e.path` to the right screen with React Navigation.
- [Test](https://straitlink.in/docs/sdks/react-native/test/): deep links, deferred links and analytics on a real phone.
