Quickstart: open your React Native app from a link (Android)

After this page, you will have one link, https://hilltop.strait.link/summer, that opens your Android app when you tap it on your phone, and your app will print the screen it should show, /product/42.

  • Task
  • ~ 10 minutes
  • Android
  • iPhone
On this page 9
  1. 1. Create a workspace
  2. 2. Tell us about your Android app
  3. 3. Make a link
  4. Shortcut: let strait init do steps 4 and 5
  5. 4. Let your app answer to its scheme
  6. 5. Add the SDK
  7. 6. Tap the link
  8. Common errors
  9. Next steps
Time
About 10 minutes
You need
A React Native app you can run on an Android phone or emulator (Flutter and Kotlin links below)
Works on
Android. iPhone has its own quickstart

Six steps. Do them in order. Each step says what to do, what to copy, and what you should see when it worked. If you don't see it, stop and check Common errors before the next step.

Two words you'll meet:

  • Deep link: a link that opens your app on a particular screen, not just its home screen.
  • SDK: the small library you add to your app. It tells your app which screen a link wants.

Native iPhone app? Follow the Quickstart for iPhone. On Expo? Steps 1 to 3 are the same; for steps 4 and 5 follow Expo. Flutter: Flutter. Kotlin: Android.

1. Create a workspace

Do this: sign up and type a name for your workspace. That name becomes your link address, https://<your-handle>.strait.link. These docs write it as hilltop.strait.link.

You should see: your link address and your publishable key (starts with st_pub_live_…) in Dashboard → Setup → Your keys. The publishable key is safe to put in your app.

2. Tell us about your Android app

Do this: open Dashboard → Apps & stores. Under Android, fill in two boxes, then press Save app details.

Box Example Where to find it
Package name com.yourcompany.yourapp applicationId in android/app/build.gradle
Custom scheme yourapp Make one up: a short lowercase word, like your app's name. It's the private address your app answers to (yourapp://)

You should see: Saved ✓ next to the button. Leave every other box empty for now.

Do this: open Dashboard → Links. In the New link form at the top, type Short path summer and Destination https://shop.example.com/product/42. Press Create.

Prefer a terminal? Paste this instead. The secret key is in Dashboard → Settings → Keys. Keep it on your computer or server, never in an app.

Terminal
export SECRET_KEY=st_live_…   # Dashboard → Settings → Keys
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" }'

The destination page doesn't need to exist. Your app only gets its path, /product/42.

You should see: https://hilltop.strait.link/summer in your link list. (The terminal answer is 201 with that shortUrl.)

Shortcut: let strait init do steps 4 and 5

In your app's folder, paste:

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

It spots a React Native, Expo, Flutter or Android app, writes the links file from step 5 with your key and address, and prints the step 4 lines and the install command with your scheme filled in. It never changes a file you already have. Add --dry-run to see everything first. If you typed your own scheme in step 2, add --scheme yourapp (with your scheme), so the printed lines match Apps & stores.

4. Let your app answer to its scheme

Do this: open android/app/src/main/AndroidManifest.xml. Inside your main <activity>, add the <intent-filter> below. Put your own scheme from step 2 where it says yourapp. Keep the filters that are already there.

android/app/src/main/AndroidManifest.xml
<activity android:name=".MainActivity" android:launchMode="singleTask" android:exported="true">
  <!-- existing intent filters stay -->
  <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>

You should see: the app builds and runs as before when you run npx react-native run-android.

5. Add the SDK

Do this: in your app's folder, paste this install command. Install it from npm; no sign-up or access request.

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

Then make a new file, links.ts, and paste this. Put your publishable key and link address in the two marked lines.

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.onLink((e) => console.log('Strait link:', e.matched, e.path, e.params));
links.start();

Last, add import './links'; near the top of your entry file (index.js or App.tsx). Rebuild the app, because the SDK adds native code.

You should see: the app starts normally and prints one line: Strait link: false undefined undefined. That's right: on the first start the SDK checks once for a link and finds none.

Do this: send https://hilltop.strait.link/summer to yourself in Google Messages or Gmail. Tap it on the phone. Don't paste it into the browser's address bar: phones only open apps from links you tap.

On an emulator, or a phone plugged in by USB, this command counts as a tap:

Terminal
adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/summer"

You should see: the browser flashes for a moment, then your app opens and prints Strait link: true /product/42 {}. Logs are in React Native DevTools (press j in the Metro terminal) or adb logcat -s ReactNativeJS. Within a minute, the tap and the app open show in Dashboard → Analytics.

WhatsApp or Instagram may show an Open in app page first. That's normal: apps' built-in browsers often won't open other apps by themselves.

Common errors

  • Chrome opens the Play Store or the website, not the app. The scheme in Apps & stores and the one in the manifest are different, or the phone has an old build without step 4. Fix the scheme, rebuild, try again.
  • The app opens but prints nothing. links.ts isn't imported when the app starts, or you didn't rebuild after step 5.
  • It prints false with reason: "not_found". The publishable key is from another workspace. Copy it again from Dashboard → Setup → Your keys. More in Troubleshooting.

Next steps