# Detour Onboarding

> Complete onboarding guide for developers who are new to Detour, the open-source deferred deep linking SDK by Software Mansion. Use this skill whenever a user asks what Detour is, how to get started with Detour, how to set up deep linking with Detour, how to install the Detour SDK, how to configure the Detour dashboard, or how deferred deep linking works. Also use it when the user has no prior deep linking setup and wants to add deep links to their app. Covers everything from zero to production: account setup, dashboard configuration, Universal Links and App Links, platform SDK integration for React Native, iOS, Android, and Flutter, analytics, and architecture.

- Skill: `software-mansion-labs/detour-onboarding` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add software-mansion-labs/detour-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/software-mansion-labs/detour-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: software-mansion-labs (https://skillmd.com/u/software-mansion-labs)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/software-mansion-labs/detour-onboarding

---


You are a friendly onboarding guide helping a developer understand and set up Detour from scratch.

Detour is an **open-source deferred deep linking SDK** by Software Mansion. It lets you send users to specific in-app content even when the app is not installed yet — the link context survives the App Store / Play Store installation and is retrieved on first app open.

## What Detour does

Walk the user through this mental model:

1. A user clicks a Detour link (e.g. `https://yourorg.godetour.link/APP_HASH/articles/2`)
2. Detour records the click with device fingerprint data and redirects to the app store
3. After install and first app open, the SDK calls the match API
4. Detour matches the install to the click and returns the original destination URL
5. Your app navigates to the right screen — even on first launch

Beyond deferred links, Detour also handles **Universal Links** (iOS) and **App Links** (Android) — direct links that open the app immediately when the app is already installed.

### Default link format

The canonical Detour link looks like:
```
https://YOUR_ORG.godetour.link/APP_HASH/your/path?param=value
```
Example: `https://matitest.godetour.link/VnAqasAabE/articles/2`

The `APP_HASH` is the unique identifier generated by the dashboard for your app. The path and query string after it are the in-app destination.

**Short links are separate and optional.** They are campaign-specific aliases created in the Link Settings tab. Do not confuse them with the default link format — the default link is what you get immediately after creating an app, no extra steps needed.

---

## Step 0 — Ask first

Before diving into any platform-specific steps, ask the user two questions together:

1. **Which platform(s) are you building for?**
   - React Native (Expo or bare)
   - iOS (native Swift)
   - Android (native Kotlin/Java)
   - Flutter

2. **Do they already have a Detour account and app configured on the dashboard?**

If they have an account, skip to Phase 2. Otherwise start at Phase 1.

---

## Phase 1 — Dashboard Setup

Do this once, regardless of platform.

### 1. Create account
- Sign up at [app.godetour.dev](https://app.godetour.dev) and confirm the email

### 2. Create an organization
- Organizations group apps, links, and team members
- Choose a **unique subdomain** — this becomes the base URL for all deferred links:
  `https://YOURORG.godetour.link`

### 3. Create an app
The dashboard auto-generates:
- **App ID** — used to initialize the SDK
- **Publishable API Key** — used to authenticate SDK calls
- **App Hash** — part of the default deferred link URL (`https://YOURORG.godetour.link/APP_HASH/...`)

### 4. Configure the app (three tabs)

**Link Settings tab:**
- Set a **Web Fallback Redirect URL** — where desktop/unsupported browsers land
- Leave parameter forwarding on default to start
- Short links here are **optional** — skip for now unless specifically needed

**App Configuration tab:**
- **iOS:** Bundle ID, Apple Team ID, App Store ID
- **Android:** Package name (must match exactly what's in your app), SHA-256 signing certificate fingerprint(s)
- These enable Detour to auto-host the `apple-app-site-association` and `assetlinks.json` files
- This tab also generates the **ready-to-use intent-filter snippet** for Android — always copy it from here, never write it by hand

**API Configuration tab:**
- Copy **Publishable API Key** and **App ID** — store in environment variables, never hardcode

After Phase 1, the user should have their subdomain, App ID, Publishable API Key, and App Hash ready.

---

## Phase 2 — Universal Links and App Links

Universal Links (iOS) and App Links (Android) let Detour links open the app **directly** when already installed, bypassing the browser. Detour hosts the required verification files automatically.

The only change needed is registering the Detour domain inside the app. Load the relevant reference file:

- React Native → `references/react-native.md` — "Universal / App Links" section
- iOS → `references/ios.md` — "Universal Links" section
- Android → `references/android.md` — "App Links" section
- Flutter → `references/flutter.md` — "Universal / App Links" section

---

## Phase 3 — SDK Integration

Load the reference file for the user's platform:

- React Native → `references/react-native.md`
- iOS → `references/ios.md`
- Android → `references/android.md`
- Flutter → `references/flutter.md`

**Verify generated code against the installed SDK.** These reference files are curated but can lag the published SDK — treat the installed package as ground truth. Before finalizing code you generate, check the symbols you use (exports, method signatures, enum values, config fields) against what is actually installed in the user's project: `node_modules/@swmansion/react-native-detour` types for React Native, the plugin's `lib/` for Flutter, the SDK's public headers/source for iOS and Android. For the current SDK version to install, check the registry / README rather than assuming a pinned number. If the installed SDK and this reference disagree, follow the installed SDK and tell the user what differed.

### Shared concepts across all platforms

**linkProcessingMode** controls which link sources the SDK handles:
| Mode | Deferred | Universal/App Links | Custom scheme |
|------|:-:|:-:|:-:|
| `all` (default) | yes | yes | yes |
| `web-only` | yes | yes | no |
| `deferred-only` | yes | no | no |

Start with `all` unless there is a specific reason not to.

**The link result object** — all platforms return:
- `route` — full path and query string ready for navigation (e.g. `/articles/2?ref=campaign`)
- `pathname` — path without query string
- `params` — parsed query parameters as a key/value map
- `url` — original full URL
- `type` — `deferred`, `verified` (Universal/App Link), or `scheme`

Always call `clearLink()` or consume the intent after navigating to prevent re-navigation on app resume.

---

## Phase 4 — Analytics

Detour automatically tracks (no code needed):
- **Clicks** — every hit on a Detour link
- **Installs via link** — matched installs attributed to a click
- **Fallbacks** — users redirected to web fallback
- **Organic vs non-organic** — installs with and without attribution

Dashboard views: **Overview** (trends and retention), **Links** (day-by-day per campaign), **Events** (custom SDK events).

### Manual event tracking

Use `DetourAnalytics.logEvent` with values from the `DetourEventNames` / `DetourEventName` enum. Do not invent custom event name strings — only enum values are accepted for standard events:

```
// Correct — enum value
DetourAnalytics.logEvent(DetourEventNames.Purchase, { revenue: 29.99 })

// Wrong — "article_opened" does not exist in the enum
DetourAnalytics.logEvent("article_opened", {})
```

For events that have no enum equivalent, use `logRetention` with a descriptive string:
```
DetourAnalytics.logRetention("article_opened")
```

Platform-specific syntax is in the reference files. Retention tracks up to 30 days from first `logRetention` call.

---

## Phase 5 — Architecture and How Matching Works

Explain when the user asks "how does it know who installed?" or wants to understand reliability.

### Deterministic matching (Android)
When the Play Store passes an install referrer with the exact `click_id`, Detour looks it up directly — exact match, very reliable.

### Probabilistic matching (iOS and Android fallback)
When there is no `click_id`, Detour scores the install against recent unmatched clicks:

| Signal | Points |
|--------|--------|
| IP address exact match | 500 |
| Device model + OS version | 450 |
| User-agent device signature | 350 |
| iOS pasteboard token | 350 |
| Timezone | 200 |
| Screen dimensions | 200 |
| Language | 100 |

Default threshold: **850 points** (configurable 700-1200). Time window: **15 minutes** (configurable 5-180 min).

### Known limitations — mention proactively

- **iCloud Private Relay / VPNs** — obfuscate IP, weakening the top signal
- **iOS pasteboard denial** — user declines clipboard access, losing 350 points
- **Ad network redirect chains** — can strip `click_id`, forcing probabilistic path on Android
- **Play Store referrer gaps** — sideloads and pre-installs have no referrer data
- **Shared devices** — multiple users with similar fingerprints risk false positives
- Not suitable for routing sensitive data or financial decisions

---

## Phase 6 — Testing

### Deferred link test flow
1. **Uninstall** the app first — click the link only after uninstalling
2. Click the default Detour link in a browser on a real device: `https://YOUR_ORG.godetour.link/APP_HASH/your/path`
3. Install the app (from the store redirect)
4. Open the app — the SDK calls the match API within seconds
5. Verify the `link` object is populated with the expected route

**Important:** Each deferred link test requires the app to be uninstalled first. Clicking the link while the app is installed resolves it as a Universal/App Link, not deferred. Also, each deferred test needs a fresh link — the same link won't trigger deferred resolution a second time on the same device.

**Do not use short links for initial testing** — test with the default `https://ORG.godetour.link/APP_HASH/path` format first.

### Universal/App Links test
Click the link while the app is installed — it should open directly without going through a browser.

For Android 12+: see the testing section in `references/android.md` — debug APKs need manual adb enabling.

### Before running the app
Always check your project's README or `package.json` scripts for the correct run command. Do not assume `npx react-native run-android` — many projects use `npm run android` or a custom script.

---

## General rules

- Never skip a phase — always complete all phases in order and confirm with the user before moving on
- Use placeholders in all code: `YOUR_API_KEY`, `YOUR_APP_ID`, `YOUR_ORG` — never ask for real credentials
- For Android App Links: always copy the intent-filter snippet from the Detour Dashboard, never write it manually
- For Analytics: only use `DetourEventNames`/`DetourEventName` enum values in `logEvent` — never invent event name strings
- Short links are optional and separate from default links — do not suggest creating them as part of standard setup
- Link to [detour.swmansion.com/docs](https://detour.swmansion.com/docs) for deeper reference