Expo deep linking (Expo Router)

After this page, links open your Expo app on the right Expo Router screen, including the first open after an install.

On this page 8
  1. 1. Install the SDK
  2. 2. Add the config plugin to app.json
  3. 3. Route links with Expo Router
  4. 4. Make a development build
  5. 5. Add your SHA-256 fingerprints
  6. Or let strait init write the setup
  7. Common errors
  8. 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 15 minutes, plus a development build
You need
An Expo SDK 51+ app using Expo Router (the config plugin needs SDK 0.10.0+), a workspace with your app in Dashboard → Apps & stores
Works on
Android, iPhone

The SDK is the same one bare React Native uses. Two things differ: link settings come from the SDK's config plugin in app.json, and you need a development build, not Expo Go. For the whole path from tap to Google Play install, follow the Expo deferred links recipe.

1. Install the SDK

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

npx expo install picks helper versions that match your Expo SDK.

You should see: all three packages in package.json.

2. Add the config plugin to app.json

The SDK ships an Expo config plugin (version 0.10.0 and later). Give it your link domain and the custom scheme from Dashboard → Apps & stores:

app.json
{
  "expo": {
    "android": { "package": "com.yourcompany.yourapp" },
    "ios": { "bundleIdentifier": "com.yourcompany.yourapp" },
    "plugins": [
      ["@straitlink/react-native", { "domains": ["hilltop.strait.link"], "scheme": "yourapp" }]
    ]
  }
}

At prebuild (npx expo run:android, npx expo run:ios, npx expo prebuild or an EAS build) the plugin writes three things:

  • iPhone: the Associated Domains entitlement applinks:hilltop.strait.link, so https://hilltop.strait.link/… opens the app once your Team ID is in Apps & stores.
  • Android: an intent filter for https://hilltop.strait.link with android:autoVerify="true", so the link opens the app once your SHA-256 fingerprints are in Apps & stores (step 5).
  • Both: the yourapp:// scheme, used when a browser hands a link to your app.

It fills Expo's own ios.associatedDomains, android.intentFilters and scheme fields, keeps anything you already have there, and adds nothing twice. A custom domain goes in the same list: "domains": ["hilltop.strait.link", "go.example.com"]. A value with a path, http:// or a wildcard is refused at prebuild with a message saying what to change.

You should see: npx expo config --type prebuild lists applinks:hilltop.strait.link under ios.associatedDomains, an intentFilters entry with "autoVerify": true and your scheme. After npx expo prebuild, android/app/src/main/AndroidManifest.xml has <intent-filter android:autoVerify="true"> with android:host="hilltop.strait.link".

Without the plugin

On SDK 0.9.x, or to write the fields yourself:

app.json
{
  "expo": {
    "scheme": "yourapp",
    "android": {
      "package": "com.yourcompany.yourapp",
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [{ "scheme": "https", "host": "hilltop.strait.link" }],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    },
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp",
      "associatedDomains": ["applinks:hilltop.strait.link"]
    }
  }
}

This is what the plugin writes. Use one or the other, not both.

New Architecture

The SDK works on React Native's New Architecture (TurboModules, Fabric, bridgeless), which is the only one in React Native 0.82 and later and the default in Expo SDK 52 and later. Its example app (Expo SDK 57, React Native 0.86) is built for Android and iOS on every change and opens links on the Android emulator and the iOS Simulator. Nothing to switch on.

Create the client (the same links.ts as bare React Native; on Expo add installTime: async () => (await Application.getInstallationTimeAsync()).getTime() from expo-application so a reinstall from a link counts again, see the reference), then subscribe in your root layout once navigation is ready:

New apps from create-expo-app keep their screens in src/app/. If yours does, put both files below in src/app/ and links.ts in src/. Expo Router ignores an app/ folder next to src/app/.

app/_layout.tsx
import { Stack, router, useRootNavigationState, type Href } from 'expo-router';
import { useEffect } from 'react';
import { links } from '../links';

export default function RootLayout() {
  const ready = useRootNavigationState()?.key;
  useEffect(() => {
    if (!ready) return;
    // Opened from a link, or first open after install: same callback.
    return links.onLink((e) => {
      if (e.matched && e.path) router.push({ pathname: e.path, params: e.params } as Href);
    });
  }, [ready]);
  return <Stack />;
}

Expo Router also tries to open every incoming link itself, and https://hilltop.strait.link/summer isn't a screen in your app. This file sends it to your first screen and lets onLink do the routing:

app/+native-intent.tsx
// Links reach the app through Strait's onLink (app/_layout.tsx), which knows the
// real destination. Keep Expo Router from routing the raw link URL.
export function redirectSystemPath({ path }: { path: string; initial: boolean }) { return '/'; }

If your app has other deep links of its own (a sign-in callback, for example), return path for those instead of '/'.

You should see: no "Unmatched route" screen when a link opens the app.

4. Make a development build

Expo Go can't load the native module, and links on your domain open your app, not Expo Go. Build your own app:

Terminal
npx expo run:android     # or npx expo run:ios; runs prebuild for you
eas build --profile development --platform android   # or build in the cloud with EAS Build

You should see: adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" opens your app/product/[id].tsx screen with id 42.

5. Add your SHA-256 fingerprints

For verified links, Dashboard → Apps & stores needs the certificate of each build you install:

Terminal
# Local builds (npx expo run:android): the project's debug key
keytool -list -v -keystore android/app/debug.keystore -storepass android | grep SHA256

# EAS builds: choose Android and your build profile; the keystore's SHA-256 is listed
eas credentials

For builds installed from Google Play, also add the Play App Signing key from Play Console → Test and release → App integrity.

You should see: adb shell pm get-app-links com.yourcompany.yourapp reports hilltop.strait.link: verified after a reinstall.

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 reads your app.json, writes links.ts and, with Expo Router, app/+native-intent.tsx (step 3; src/links.ts and src/app/+native-intent.tsx when your screens live in src/app/), and prints the install commands, the app.json block for step 2 and the root layout code, filled in with your package, scheme and host. It never edits your existing files.

Common errors

  • Links open Expo Go or nothing at all. You're running in Expo Go. Use the development build from step 4.
  • "Unmatched route" after a tap. app/+native-intent.tsx is missing or returns path for your link domain.
  • Works locally, not from EAS. The EAS keystore's SHA-256 isn't in Settings (step 5).

Next steps

  • Test: deep links, deferred links from Google Play, and analytics.
  • Events & revenue: put purchases on the tap that brought them.