# Migrate from Branch

> After this guide, you will have your Branch links rebuilt on Strait with the same paths, fallbacks, previews and campaigns, an app that opens them with the Strait SDK, and a safe plan to close Branch.

- Time: About 15 minutes to import. The whole move is about a day of developer work plus one app release
- You need: Your Branch link export (CSV or JSON), your app's code, a Strait workspace
- Works on: Android, iPhone, React Native, Flutter, Unity, web

Source: https://straitlink.in/docs/migrate-from-branch/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

Five steps. Each says what to do, what to copy and how you know it worked.

## 1. Export your links from Branch

**Do this:** in your Branch dashboard, download your link export as CSV or JSON. Don't edit it. A CSV's first row must be Branch's own column names (`url`, `alias`, `$canonical_url`, `$deeplink_path`, `~campaign` and so on).

```txt title="branch-links.csv (shortened)"
url,$canonical_url,$deeplink_path,$ios_url,$android_url,$og_title,~campaign,~channel,~tags
https://yourapp.app.link/summer-sale,https://shop.example.com/sale/summer,,,,Summer Sale,summer_2026,instagram,"sale,summer"
https://yourapp.app.link/p42,https://shop.example.com/products/42,product/42,https://shop.example.com/ios/42,https://shop.example.com/android/42,,,,
```

**You should see:** one file with a row (or JSON entry) per Branch link.

## 2. Preview the import

**Do this:** open **Dashboard → Import → From Branch**. Choose the file and press **Preview**.

Each row shows the new short path, the screen your app will open, fallbacks, preview, campaign and tags. This is how fields move:

| Branch | Strait |
|---|---|
| `alias`, or the end of the short link (`yourapp.app.link/summer-sale` → `summer-sale`) | The short path (slug). Letters, numbers, `-` and `_`, up to 64; other characters become `-` |
| `$deeplink_path` (what your app routes on) | The path your app gets, `e.path`. `product/42` becomes `/product/42` on your website's address |
| `$canonical_url`, `$fallback_url`, `$desktop_url` | Where people without the app, and computers, go |
| `$ios_url`, `$android_url` | `iosFallbackUrl`, `androidFallbackUrl` |
| `$og_title` (or `$marketing_title`), `$og_description`, `$og_image_url` | The chat preview: `title`, `description`, `imageUrl` |
| `~campaign` | `campaign` |
| `~channel` | `utm_source` on the destination (how Analytics names the channel) |
| `~tags`, `~feature` | Tags (the feature becomes a `feature:<name>` tag) |

Rows with a problem say why in plain words. Every field we don't use (like `~stage`, `$one_time_use` or your own custom keys) is listed too.

**You should see:** a table of your links. Any row with a problem says what's wrong.

## 3. Import

**Do this:** press **Import N links**.

Running it twice is safe: a short path that already exists is reported, never overwritten. Rows that failed can be downloaded as a CSV, fixed, and imported again with **Bulk create (CSV)**.

For thousands of links, use the API instead: `POST /v1/links/batch` takes up to 500 links per call with your **secret key** (the server-only key from **Dashboard → Settings**).

```bash
curl https://strait.link/v1/links/batch \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {
        "slug": "p42",
        "longUrl": "https://shop.example.com/product/42",
        "desktopUrl": "https://shop.example.com/products/42",
        "iosFallbackUrl": "https://shop.example.com/ios/42",
        "androidFallbackUrl": "https://shop.example.com/android/42",
        "title": "Product 42",
        "campaign": "summer_2026",
        "tags": ["sale"]
      },
      { "slug": "summer-sale", "longUrl": "https://shop.example.com/sale/summer?utm_source=instagram" }
    ]
  }'
```

```json
{
  "results": [
    { "index": 0, "ok": true, "status": 201, "link": { "slug": "p42", "shortUrl": "https://<handle>.strait.link/p42", … } },
    { "index": 1, "ok": false, "status": 409, "error": "slug already exists in this workspace" }
  ],
  "summary": { "total": 2, "created": 1, "failed": 1 }
}
```

Each item gets its own answer: `201` made, `400` invalid, `402` plan limit reached, `409` short path taken. See the [REST API](https://straitlink.in/docs/api/#batch-create).

**You should see:** a summary of what was made, and your links in **Dashboard → Links** at `https://<handle>.strait.link/<path>`.

## 4. Swap the SDK in your app

**Do this:** remove the Branch SDK and add ours ([React Native](https://straitlink.in/docs/sdks/react-native/), [Flutter](https://straitlink.in/docs/sdks/flutter/), [Android](https://straitlink.in/docs/sdks/android/), [iOS](https://straitlink.in/docs/sdks/ios/), [Unity](https://straitlink.in/docs/sdks/unity/)). Then swap the red lines for the green ones:

```diff
- branch.subscribe(({ params }) => { if (params['+clicked_branch_link']) route(params.$deeplink_path); });
+ links.onLink((e) => { if (e.matched && e.path) route(e.path, e.params); });
```

```diff
- new BranchEvent(BranchEvent.Purchase, null, { revenue: 49.99, currency: 'USD' }).logEvent();
+ links.trackEvent('purchase', { value: 49.99, currency: 'USD' });
```

On native Android and iOS it's the same idea: drop `Branch.getAutoInstance()` and `initSession`, start the Strait client at launch, and listen with `onLink`. Links tapped before an install arrive in the same callback with `kind: 'deferred'`.

Last, point app verification at your new address. Android: set the intent filter's `android:host` to `hilltop.strait.link` and add your SHA-256 fingerprints in **Apps & stores**. iPhone: set Associated Domains to `applinks:hilltop.strait.link` and add your Team ID and bundle ID in **Apps & stores** ([how](https://straitlink.in/docs/app-links/)).

**You should see:** tapping `https://hilltop.strait.link/p42` in Messages or Gmail opens your app on the product 42 screen.

## 5. Switch over, then retire Branch

**Do this:** go in this order.

1. **Ship the app update.** You can keep the Branch SDK in this release, so old Branch links still open the app.
2. **Make new links on Strait.** Point your backend, marketing tools and share buttons at `POST /v1/links` (or the [Node SDK](https://straitlink.in/docs/sdks/node/)).
3. **Replace old links** wherever you control the text: website, emails, app screens, QR codes you can reprint.
4. **Keep Branch active** while old `app.link` links still get taps. Links on `app.link` work only while your Branch account is active.
5. **Remove the Branch SDK** in a later release, once taps on old links have stopped.

**You should see:** new taps in **Dashboard → Analytics**, and old Branch links getting fewer taps each week.

## Frequently asked questions

### What doesn't move from Branch?

Analytics history: Branch's clicks, installs and attribution stay in Branch, so export the reports you need first. Also not moved: the `app.link` domain (Branch owns it), custom link data beyond the path and query, and settings like `$one_time_use`, journeys and banners. Separate iOS and Android deep link paths become one path; the Android one is kept and the row warns you.

### Can I bring my Branch custom domain?

Yes, on Starter and up: [Custom domains](https://straitlink.in/docs/custom-domains/). Every workspace also keeps `<handle>.strait.link`.

### What does Strait cost?

Free up to 25,000 taps a month, no card. App opens are never billed. Paid plans are on [Pricing](https://straitlink.in/pricing/).

## Common errors

- **A row says the destination isn't https.** Every destination must start with `https://`. Fix it in the file and preview again.
- **A short path is reported as taken.** Another link in your workspace already uses it. Rename it in the file, or keep the existing link.
- **The app opens the website, not the app.** The new build with `hilltop.strait.link` isn't installed, or fingerprints or Team ID are missing in **Apps & stores**.

## Next steps

- [Test](https://straitlink.in/docs/sdks/react-native/test/): check direct and deferred links on a real phone.
- [Analytics: how we count](https://straitlink.in/docs/analytics/): how taps, opens and installs compare with Branch's numbers.
