Migrate from Firebase: import links and cut over

After this page, you will have your old links on your own link address, a backend that makes new links with Strait, and a real phone that proves both work.

On this page 8
  1. 1. Collect your old links
  2. 2. Import them in the dashboard
  3. 3. Or import them with the batch API
  4. 4. Switch your backend to POST /v1/links
  5. 5. Check the whole path on a real phone
  6. 6. Replace the links people see
  7. Common errors
  8. Next steps
Time
About 1 hour
You need
Your old links (an export, a CSV or your own records), a secret key, the app update from Swap the SDK
Works on
Android, iPhone

Already used Move your links in one step? Your links are rebuilt: skip to step 4.

Do this: put every old link you still want in one file, one per line. Any of these forms works:

  • Firebase short links with the long form attached, like https://yourapp.page.link/abc?link=https%3A%2F%2Fshop.example.com%2Fp%2F42
  • Plain destination URLs
  • A CSV with a header row. We recognise link, url, destination or longUrl for the destination, and slug, short, path or key for the slug.
links.csv
short,link
https://yourapp.page.link/summer,https://shop.example.com/product/42
https://yourapp.page.link/invite,https://shop.example.com/invite?ref=abc

No export? Your backend's database or logs usually hold the link values it sent to the shortLinks API.

You should see: one file with every link you still want to work.

2. Import them in the dashboard

Do this: open Dashboard → Import → Firebase import (the tab next to Move from Firebase; this one shows every row before anything is made). Paste the list, or the CSV's text, and press Preview. We pull the real destination out of each Firebase link's link= parameter, keep the old short code as the slug where we can, and show a preview with any rows that can't be imported (and why) before you confirm.

You should see: a preview listing each new https://hilltop.strait.link/<slug> link, then the links in Dashboard → Links.

3. Or import them with the batch API

Do this (only for thousands of links): save this script next to links.csv and run SECRET_KEY=… node import.mjs. It sends up to 500 links per call to POST /v1/links/batch. Each item takes the same fields as POST /v1/links:

import.mjs (Node 18+)
import { readFileSync } from 'node:fs';

const rows = readFileSync('links.csv', 'utf8').trim().split('\n').slice(1).map((l) => l.split(','));
const items = rows.map(([short, link]) => ({
  slug: new URL(short).pathname.slice(1),   // keep the old short code
  longUrl: link,
  campaign: 'fdl_import',
}));

for (let i = 0; i < items.length; i += 500) {
  const res = await fetch('https://strait.link/v1/links/batch', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SECRET_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ links: items.slice(i, i + 500) }),
  });
  const { summary, results } = await res.json();
  console.log(summary, results.filter((r) => !r.ok));
}

Every item gets its own result, so one bad row never fails the batch. A slug that already exists is a 409 for that item only, so re-running the script is safe.

You should see: { total: 2, created: 2, failed: 0 } for the example file. Failed items show their status and error.

4. Switch your backend to POST /v1/links

Do this: wherever your backend called Firebase's shortLinks API, swap the red lines for the green ones. Keep the secret key in an environment variable (SECRET_KEY), never in code.

share.js
- const res = await fetch(`https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=${FIREBASE_API_KEY}`, {
-   method: 'POST',
-   body: JSON.stringify({ dynamicLinkInfo: { domainUriPrefix: 'https://yourapp.page.link', link: productUrl,
-     androidInfo: { androidPackageName: 'com.yourcompany.yourapp' }, socialMetaTagInfo: { socialTitle: title } },
-     suffix: { option: 'SHORT' } }),
- });
- const { shortLink } = await res.json();
+ const res = await fetch('https://strait.link/v1/links', {
+   method: 'POST',
+   headers: { Authorization: `Bearer ${process.env.SECRET_KEY}`, 'Content-Type': 'application/json' },
+   body: JSON.stringify({ slug: `p-${crypto.randomUUID().slice(0, 8)}`, longUrl: productUrl, title }),
+ });
+ const { shortUrl: shortLink } = await res.json();

The same call in Python:

share.py
import os, uuid, requests

res = requests.post(
    "https://strait.link/v1/links",
    headers={"Authorization": f"Bearer {os.environ['SECRET_KEY']}"},
    json={"slug": f"p-{uuid.uuid4().hex[:8]}", "longUrl": product_url, "title": title},
)
short_link = res.json()["shortUrl"]

Or use the Node SDK: await links.createLink({ slug, longUrl, title }). The package name and bundle ID are no longer sent per link: they're in Dashboard → Apps & stores.

You should see: your backend returns https://hilltop.strait.link/… links, and they appear in Dashboard → Links.

5. Check the whole path on a real phone

Do this: before you change links people can see, paste these two commands. They show what a tap would do on Android and on iPhone, without counting a tap:

Terminal
curl "https://strait.link/v1/simulate?url=https%3A%2F%2Fhilltop.strait.link%2Fsummer&ua=android" -H "Authorization: Bearer $SECRET_KEY"
curl "https://strait.link/v1/simulate?url=https%3A%2F%2Fhilltop.strait.link%2Fsummer&ua=iphone" -H "Authorization: Bearer $SECRET_KEY"

Then, on a phone with the app update:

  1. Tap an imported link in Messages or Gmail. The app opens on the right screen.
  2. Uninstall the app. Tap the link again. Install from Google Play internal testing and open it. The same screen opens. Paste your domain into the App Links checker too.

You should see: the expected decision for each device, the app opening on the right screen, and the tap, open and install in Analytics.

Do this: work through the list from the plan: email and push templates, your website, app screens, and SMS templates. For SMS sent in India, whitelist <handle>.strait.link in your DLT template. Printed QR codes that point at page.link can't be changed; reprint them when you can.

You should see: a search of your templates and website for page.link finds nothing.

Common errors

  • Imported links open the website, not the app. The app update with your new link domain isn't installed yet, or your SHA-256 fingerprints are missing (go-live checklist).
  • 402 while importing. The import is past your plan's monthly link limit. Links created so far keep working; upgrade or import the rest next month.
  • 409 for some slugs. Those slugs already exist in your workspace (often from an earlier run). That's safe to ignore.

Next steps

  • Analytics: how we count: how taps, opens and installs compare with the Firebase numbers you had.
  • Webhooks: get installs and opens on your server, which Dynamic Links never offered.