Deferred deep links in React Native, end to end
After this guide, someone who taps your link without your React Native app installed goes through Google Play and lands on the link's screen on the first launch, and you can see that tap, install and open in Analytics.
On this page 9
- Time
- About 45 minutes of work, plus the first Google Play review (up to 7 days, per Google)
- You need
- A bare React Native app (0.72 or newer), a Strait workspace with your app in Apps & stores, a Google Play developer account, an Android phone
- Works on
- Android (proven on a real phone). iPhone uses the same code.
This page strings the separate React Native pages into one path for the case that matters most to growth teams: a new user. Each step links to the page with more detail. The same path for other stacks: Expo · Flutter.
1. Make a link for one screen
In Dashboard → Links → New link, set the slug summer and the destination https://shop.example.com/product/42?ref=SUMMER. Or from your server:
curl https://strait.link/v1/links \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "slug": "summer", "longUrl": "https://shop.example.com/product/42?ref=SUMMER", "campaign": "summer_2026" }'Your app receives the destination's path and query (/product/42, { ref: 'SUMMER' }), so use paths your app already routes on.
You should see: the link https://hilltop.strait.link/summer in the Links list.
2. Install the SDK with the Play Install Referrer
On Android, the link travels through the install inside the Google Play Install Referrer. The SDK reads it for you once you pass the referrer module:
npm install @straitlink/react-native@0.11.6 @react-native-async-storage/async-storage react-native-play-install-referrerimport 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
endpoint: 'https://hilltop.strait.link', // your link domain
storage: AsyncStorage, // keeps the once-per-install flag
installReferrer: fromPlayInstallReferrer(PlayInstallReferrer),
});
links.start();Import ./links once from index.js, then rebuild with npx react-native run-android (the SDK adds a native module). Add the intent filters from Install & set up, step 3.
You should see: the app starts as before, and @straitlink/react-native is in package.json.
3. Route every link, including the deferred one
The deferred link arrives through the same onLink callback as any other link, once, on the first launch after the install. onLink also replays events from before you subscribed, so subscribing when the navigator is ready never misses it.
First, one file that maps a link's path to a screen (the same helper as Receive links; skip it if you already have it):
import { createNavigationContainerRef } from '@react-navigation/native';
export const navigationRef = createNavigationContainerRef<any>();
// Map a link's path to one of your screens.
export function openPath(path: string, params: Record<string, string> = {}) {
const product = /^\/product\/([^/]+)$/.exec(path);
if (product) navigationRef.navigate('Product', { id: product[1], ...params });
else navigationRef.navigate('Home');
}Then subscribe when the navigator is ready:
import { NavigationContainer } from '@react-navigation/native';
import { links } from './links';
import { navigationRef, openPath } from './navigation';
export default function App() {
return (
<NavigationContainer
ref={navigationRef}
onReady={() => links.onLink((e) => {
if (e.kind === 'deferred') console.log('Strait first open:', e.route, e.matched, e.reason);
if (e.matched && e.path) openPath(e.path, e.params);
})}
>
{/* your navigator */}
</NavigationContainer>
);
}You should see: adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" opens the Product screen. This proves the routing; the next steps prove the install.
4. Decide what a new user sees first
On the first launch the SDK always answers once with kind: 'deferred'. When matched is false, reason is no_match (most installs don't come from a link) or network (the check runs again on the next launch). Show your usual onboarding in both cases, and skip it when a link matched:
import { links } from './links';
// Resolves with the link's path for a new user who came from a link, or null.
export const firstOpenPath = new Promise<string | null>((resolve) => {
const off = links.onLink((e) => {
if (e.kind !== 'deferred') return;
off();
resolve(e.matched && e.path ? e.path : null);
});
});Keep a short loading screen while you wait. Receive links, step 3 has one.
You should see: a fresh debug install, with no link tapped, logs Strait first open: fingerprint false no_match and shows your onboarding.
5. Ship a Google Play internal-testing build
A build from Android Studio has no install referrer, so this test needs a build installed from Google Play:
- Upload a release build to internal testing in Play Console and add yourself as a tester.
- In Dashboard → Apps & stores → People without the app, choose Always Google Play while the app isn't public. (The default sends people to your website while the Play listing isn't live.)
You should see: the build listed as available to testers in Play Console. Google says the first review can take up to 7 days, or longer in exceptional cases (Play Console Help).
6. Tap, install, open
- Uninstall the app from the phone.
- Send yourself
https://hilltop.strait.link/summerin WhatsApp or Messages and tap it. Google Play opens on your app. - Install from Play and open the app.
You should see: the app opens directly on the Product screen for 42, with ref SUMMER in its params, and adb logcat shows Strait first open: install_referrer true. The check runs once per install; uninstall to repeat it.
7. See the install in Analytics
Open Dashboard → Analytics and choose summer_2026 in the Campaign filter. To put revenue on the same tap, record a purchase from the app with links.trackEvent('purchase', { value: 499, currency: 'INR' }) (Events & revenue).
You should see: your tap on summer, one install with match method install_referrer joined to that exact tap, and one app open from a new user. A test purchase appears under the same campaign.
Common errors
- The first open lands on the home screen. The app came from Android Studio or a shared APK, not Google Play, or the Apps & stores choice in step 5 still sends people to your website. Test page.
- Analytics shows the tap but no install. The phone was offline on the first launch, so the report is saved and sent on a later launch. Open the app again on a network.
- The deferred event fires before the navigator exists. Navigating from it crashes or does nothing. Subscribe in
onReady, as in step 3.
Next steps
- Go-live checklist: verified links, iPhone and keys before real users tap.
- Test on a real phone: deep links, deferred links from Google Play and analytics, one check at a time.