Skip to content

README.md

Latest commit

 

History

History
170 lines (108 loc) · 9.38 KB

README.md

File metadata and controls

170 lines (108 loc) · 9.38 KB
Raw

Detour Expo Bare Example

The most minimal integration of @swmansion/react-native-detour — no router, no navigation library. DetourProvider is initialized with SDK config and a single screen renders the raw useDetourContext() state. No router or navigation.

Use this as a quick SDK smoke test or as a base before adding your own routing.

Related examples:

Test flow

Launch the app — once the startup check completes, isLinkProcessed turns true. With no pending link, type, url, and route are empty.

Trigger a Universal/App link (see Triggering links) — type, url, and route populate with the resolved link data.

To test the deferred case: follow the Deferred deep link setup before installing. The deferred check only runs once - the SDK writes a persistent flag on first launch, so subsequent launches skip it. Reinstalling is needed to re-trigger the deferred path.

A custom-scheme link (detour-expo-bare://details) populates the same type, url, and route fields (with type: scheme) — see Triggering links.


Resolved Detour link state


Resolved link state. The screen after a Detour link is resolved with isLinkProcessed: true and type, url, and route filled in.

Set up Detour

You need a Detour account to register this app and generate its credentials. Sign up and open the Detour Dashboard. If you run into issues during setup, the Dashboard Walkthrough covers each step in detail.

1. Register the app

Create an organization and add a new app. Detour assigns it a base link URL of the form https://<your-org>.godetour.link/<your-app-hash> visible in Link settings section.

In Link settings, the dashboard asks for a fallback Redirect URL to mark setup as complete. It only controls where web traffic lands — it has no effect on the deferred or Universal/App link flows these examples test, so it can be left empty or filled with a placeholder URL for local development. For production, see Full app configuration.

→ Dashboard › Apps

Detour Dashboard organization creator Detour Dashboard app creator

Detour Dashboard app link details


Dashboard. Create an organization (top-left), create a new app (top-right), and use the generated link (marked with red) in Link settings (bottom).

2. Configure the platforms

Open App configuration and fill in the platform details:

  • iOS: set Bundle ID to detourreactnative.expobare and provide Team ID and App Store ID. The Team ID must be your real Apple Developer Team ID — the one the build is signed with (DEVELOPMENT_TEAM in Xcode › Signing & Capabilities, also shown under Apple Developer › Membership). A placeholder or mismatched Team ID makes the Universal link open in Safari instead of the app. The App Store ID can stay a placeholder for local development.
  • Android: set package name to detourreactnative.expobare and add a SHA-256 certificate fingerprint. The fingerprint must match the keystore that signs the build — a wrong value makes Android open the App link in the browser instead of the app. For local development (npx expo run:android), use the local debug keystore fingerprint. See Testing Android App Links for more info.

The dashboard generates the associatedDomains and intent-filter snippets to paste into app.json (below).

For a production integration, fill all fields with real values. See App configuration for full guidance.

→ Dashboard › App configuration

Detour Dashboard App configuration


Dashboard › App configuration. iOS and Android filled configurations with generated integration code snippets ready to copy.

3. Copy your credentials

Open API configuration and copy your appID and publishable apiKey into this example's .env.

→ Dashboard › API configuration

Detour Dashboard API configuration


Dashboard › API configuration. The API configuration panel with appID and the publishable apiKey ready to copy.

Configuring app.json

Replace the placeholders in app.json with the values from the dashboard's App configuration section:

  • <your-org> — your organization slug
  • <your-app-hash> — the path prefix assigned to your app
"ios": {
  // ...
  "associatedDomains": ["applinks:<your-org>.godetour.link"]
},
"android": {
  // ...
  "intentFilters": [{
    // ...
    "data": [{ "scheme": "https", "host": "<your-org>.godetour.link", "pathPrefix": "/<your-app-hash>" }]
  }]
}

Universal Links not opening the app? Add ?mode=developer to the associatedDomains entry: "applinks:<your-org>.godetour.link?mode=developer". This bypasses Apple's CDN and fetches the AASA file directly from your domain on every launch instead of relying on a potentially stale cached version. Requires Settings → Developer → Associated Domains Development to be enabled on the device and a development-signed build. Remove it before submitting to TestFlight or the App Store.

These same values go into the simulator commands in the next section.

Triggering links

Deferred deep link

Follow these steps to test the deferred flow:

  1. Uninstall the app or clear its data to start from a clean state.
  2. Open a Detour link in the device's mobile browser.
  3. Install and launch the app — the SDK resolves the link automatically.

Note: On Android, the install referrer is typically unavailable in development builds, so deferred matching falls back to probabilistic signals (IP, device fingerprint) only. See Limitations & Known Issues.

Alternatively on iOS, you can also copy the link to your clipboard before uninstalling — the SDK reads the clipboard on first launch (shouldUseClipboard: true), so you can skip the browser step. It simulates a link clicked before the app was installed.

Universal / App link

Open a Detour link directly from the terminal:

# iOS simulator
xcrun simctl openurl booted "https://<your-org>.godetour.link/<your-app-hash>/"

# Android emulator
adb shell am start -a android.intent.action.VIEW -d "https://<your-org>.godetour.link/<your-app-hash>/"

Alternatively, paste the link into Notes or Messages on the device and tap it — this uses the same OS routing path a real user would.

Custom scheme 
# iOS simulator
npx uri-scheme open "detour-expo-bare://details" --ios

# Android emulator
npx uri-scheme open "detour-expo-bare://details" --android

For more cases and gotchas, see Testing & Troubleshooting.

Quick start

  • Install dependencies from the repo root: pnpm install
  • Configure this app in the Detour Dashboard using identifiers from app.json (for example ios.bundleIdentifier, android.package).
  • Use the values from the dashboard's API configuration section to fill .env and update app.json with the generated integration code.
  • Run prebuild for this example: pnpm prebuild
  • Start the example: pnpm start
  • Run on device/simulator: pnpm ios or pnpm android

See also