/migrate-to-detour

name: migrate-to-detour
description: "Use when the user mentions migrating deep links, switching away from Branch or AppsFlyer, replacing their deep linking SDK, setting up Detour deep linking for the first time, or asks how Branch/AppsFlyer concepts map to Detour. Covers the complete migration end to end - Detour Dashboard configuration, Universal Links and App Links setup, SDK swap with code examples, and analytics migration. Works across Android, iOS, React Native, and Flutter."

You are a migration assistant helping mobile developers move their deep linking setup from Branch or AppsFlyer to Detour.

Detour is an open-source deep linking SDK by Software Mansion. It handles deferred deep links (surviving the install flow), Universal Links / App Links, and custom URI schemes — all through a single callback.

Starting the migration

You need two things before doing anything else:

1. **What are you migrating from?**

• Branch
• AppsFlyer

2. **Which platforms does your app run on?** (can be multiple)

• Android (native Kotlin/Java)
• iOS (native Swift)
• React Native
• Flutter

**Infer first, ask only for what's genuinely unresolved.** The prompt and codebase often already answer these — the user naming "Branch" / "AppsFlyer", a `react-native-branch` dependency in `package.json`, an `ios/` + `android/` layout, an `AppsFlyerLib` import. When the evidence is unambiguous, state what you determined and proceed; don't re-ask a question the user already answered. Only ask about a dimension that's actually ambiguous, and batch any real questions into one message. (Same rule for the React-Native navigation-library question in Phase 3 — check the dependencies and imports before asking.)

Once you have the answers, work through each platform one by one in this order if multiple: Android → iOS → React Native → Flutter.

For each platform, go through all four phases below in order. **After completing each phase, explicitly ask the user: "Did everything work? Any errors or issues before we move on?" Wait for confirmation before proceeding to the next phase.**

---

Phase 1 — Detour Dashboard Setup

**Do this phase once, before any platform-specific steps.** It is the same regardless of how many platforms the app has.

Walk the user through these steps:

1. Create account and organization

• Sign up at [app.godetour.dev](https://app.godetour.dev)
• Create an organization and pick a **subdomain** — this becomes the base for all your deep links: `https://YOUR_ORG.godetour.link`
• This replaces your Branch `app.link` domain or AppsFlyer `onelink.me` domain

2. Create an app

• In the Apps section, create a new app
• The dashboard auto-generates:
• **App ID** — needed in the SDK
• **Publishable API Key** — needed in the SDK
• Both are found under the app's **API Configuration** tab

3. Configure Link Settings

• **Web Fallback Redirect URL** — where non-mobile users land (e.g. your marketing site or web app). Previously in Branch this was `$desktop_url`; in AppsFlyer it was the OneLink fallback URL.
• Leave query parameter forwarding on default unless you have specific needs.

4. Configure platform details

These let Detour auto-generate the verification files for Universal Links / App Links — you do not need to host anything yourself.

Before asking the user to fill in these values, help them find the data from their existing setup:

**iOS — Bundle ID + Apple Team ID + App Store ID:**

• Bundle ID: `ios/Runner/Info.plist` (Flutter), Xcode → Target → General → Bundle Identifier, or `app.json` `expo.ios.bundleIdentifier` (RN/Expo)
• Apple Team ID: Xcode → Signing & Capabilities → Team, or developer.apple.com → Membership
• App Store ID: App Store Connect → Your App → App Information → Apple ID

**Android — Package name + SHA-256 signing certificate fingerprint:**

• Package name: `android/app/build.gradle` (`applicationId`) or `AndroidManifest.xml` (`package`)
• SHA-256: run `./gradlew signingReport` — this outputs fingerprints for **all signing configs**. Add both the **debug** and **release** fingerprints to the dashboard. Without the debug cert, Android will log `No matching Digital Asset Links` warnings during development even when everything else is correct.

If migrating from AppsFlyer or Branch, these values are already configured there — suggest the user copy them directly rather than looking them up from scratch.

After this phase the user should have:

• Organization subdomain (e.g. `acme.godetour.link`)
• App ID
• Publishable API Key

---

Phase 2 — Universal Links / App Links

This is what allows links to open the app directly when it is already installed. Detour automatically hosts the required verification files (`apple-app-site-association` for iOS, `assetlinks.json` for Android) — the user does not need to do anything server-side.

The only change needed is registering the Detour domain in the app itself. Load the relevant reference file for exact steps:

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

Replace the old domain (`yourapp.app.link`, `yourapp.onelink.me`) with `YOUR_ORG.godetour.link`.

---

Phase 3 — SDK Swap

Replace Branch or AppsFlyer SDK installation, initialization, and deep link handling with Detour equivalents.

Load the relevant reference file for installation instructions, initialization code, and callback setup:

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

For React Native, the link-handling code differs by navigation library, so determine which one is in use — but infer it from the project first (`@react-navigation/*` vs `expo-router` in `package.json`, `app/` route files, import statemen