How to migrate deep links to a new MMP without breaking them

What is a deep link migration?

A deep link migration is the move of every live link domain, link path and deferred deep link from one link provider to another, without sending users who tap an old link to an error page or the wrong screen.

It is usually the riskiest part of an MMP switch, because links live in places you no longer control: printed QR codes, old emails, creator bios and ads that still run. The migration planner puts link work in its own track for that reason.

Associated domain file: the apple-app-site-association (AASA) file on iOS, or assetlinks.json on Android, that proves an app may open links on a domain.

Why can one domain only point at one provider?

Because each domain serves exactly one AASA file and one assetlinks.json file, from whoever hosts the domain. Two link providers cannot both answer for the same hostname at the same time.

Apple and Google set the rules:

• iOS: the AASA file lives at https://<domain>/.well-known/apple-app-site-association, served over https with a valid certificate and no redirects. Each subdomain needs its own Associated Domains entry and must serve its own file.
• iOS caching: since iOS 14, devices fetch the AASA file through an Apple-managed CDN, not directly from your server.
• Android: for each hostname in your intent filters, the system checks https://<hostname>/.well-known/assetlinks.json.
• Android timing: on Android 15+, assetlinks.json changes can take up to seven days to reach all devices. On Android 14 and lower, updates are usually picked up only when the app is installed or updated (Android docs).

The deeplinkdoctor guide to the AASA file covers the file format and common validation errors.

Keep the domain or move to a new one?

There are two paths, and each has a cost.

Keep the existing domain

• Old links keep the same hostname, so printed QR codes and creator bios still reach your infrastructure.
• You repoint DNS to the new provider, which then serves the AASA and assetlinks.json files.
• The new provider does not know your old link paths. Every old path must be recreated on the new provider, or it will resolve to nothing.
• Branch's Firebase Dynamic Links guide describes this pattern: keep a custom domain by recreating links with the same alias, with brief downtime when the CNAME switches.

Start a new domain

• Old and new domains run side by side, so there is no DNS cutover moment.
• Both domains must be in your app's Associated Domains and intent filters for as long as old links are live.
• Old links keep working only while the old provider still hosts the old domain. What happens after the account ends is not published by any of the vendors below.

What each vendor says about its link domains

Vendors set up custom link domains in different ways, and some limit what you can change later.

Two details matter most. Branch says changing NS or CNAME records makes Branch the authoritative host and you "will lose access" to that subdomain, and advises against using your main website domain (Branch docs). Adjust says its Enterprise domain cannot be edited or deleted by the customer once configured, and that changes go through support (Adjust docs).

If you are leaving Branch in particular, the Branch exit notes cover its domain rules in more detail.

Inventory every live link first

You cannot migrate links you do not know about. Before any DNS change, list:

• Paid ads: every tracking or deep link in active campaigns, by network.
• QR codes: packaging, posters, event signage and print ads. These cannot be edited once printed.
• Owned channels: email templates, push campaigns, SMS, in-app banners and your website.
• Creator and influencer bios: links in profiles and pinned posts, which you often cannot edit yourself.
• Partner placements: affiliate links and referral programmes.
• Paths and parameters: the deep link path and any parameters each link passes, so the new link can open the same screen.

Export the link list from the old provider while you still have dashboard access.

Do not forget deferred deep links

Deferred deep link: a link that sends a new user to the store, then opens the intended screen after the first install and launch.

• A deferred deep link depends on the SDK that owns the link being in the build the user installs.
• Removing the old SDK while old links are still live means installs from those links lose their deferred destination.
• Plain App Links and Universal Links do not do deferred deep linking at all, according to Google's own migration guide.
• Test deferred routes for each link type on both platforms before you retire the old SDK, which the parallel SDK guide covers.

A safe cutover order

1. Inventory every live link, path and parameter, as above.
2. Set up links on the new provider: the new domain, or the recreated paths ready for the kept domain.
3. Ship an app update that lists every domain you will use in Associated Domains and intent filters. Android 14 and lower devices only re-check assetlinks.json on install or update, so this release must go out first.
4. Wait for adoption of that release. How long typically depends on your release cycle and how quickly users update.
5. Switch DNS (kept domain) or start publishing new links (new domain).
6. Allow up to seven days for Android 15+ devices to pick up assetlinks.json changes before judging failures.
7. Replace links you control: ads, emails, push, website. Ask creators and partners to update bios and placements.
8. Retire the old SDK and domain only when traffic to old links has dropped to what you can accept losing.

The full switch checklist puts these steps alongside the SDK, network and SKAN work.

This short explainer on deferred deep linking defines the moving parts on both platforms.