The safest way to migrate between deep linking platforms is to run both simultaneously for a period. Parallel running lets you validate the new platform with real traffic while the old platform continues to serve as a safety net. If something goes wrong, you can route traffic back to the old platform immediately.<\/p>\n\n\n\n
This approach adds complexity, but it dramatically reduces risk. This guide covers how to set up parallel operation, manage traffic routing, handle SDK coexistence, and plan the cutover. For the overall migration plan, see migration timeline planning<\/a>. For analytics continuity during parallel running, see analytics data migration<\/a>.<\/p>\n\n\n\n A "big bang" migration (shut down old platform, turn on new platform) is faster but riskier. If anything goes wrong, all your deep links break at once.<\/p>\n\n\n\n Parallel running provides:<\/p>\n\n\n\n The key to parallel running is traffic routing. Both platforms need to handle requests for your deep link domain, but each request should go to exactly one platform.<\/p>\n\n\n\n Route all traffic to one platform at a time. Simple, but does not support gradual rollout.<\/p>\n\n\n\n This is not true parallel running; it is a cutover. Use this only if you cannot implement traffic splitting.<\/p>\n\n\n\n Place a reverse proxy (Nginx, Caddy, Cloudflare Workers) in front of both platforms. The proxy decides which platform handles each request.<\/p>\n\n\n\n The proxy routes based on the link path:<\/p>\n\n\n\n This lets you create new links on the new platform (under Split traffic by percentage using a load balancer or CDN edge worker:<\/p>\n\n\n\n Running two deep linking SDKs in the same app requires careful configuration to avoid conflicts.<\/p>\n\n\n\n Both SDKs will try to:<\/p>\n\n\n\n On iOS, use the SceneDelegate to route incoming links to the correct SDK:<\/p>\n\n\n\n On Android, you cannot have two SDKs both registered for the same domain in intent filters. Instead, handle all App Links in your Activity and delegate to the correct SDK:<\/p>\n\n\n\n On Android, the Google Play Install Referrer API<\/a> can only be read reliably once. Configure the new SDK to read it first:<\/p>\n\n\n\n Both platforms may need to serve verification files for your domain. Since only one server can respond to requests for The AASA file supports multiple Since both platforms serve links for the same app, the AASA file content should be identical. The critical fields are your Team ID and Bundle ID, which do not change between platforms.<\/p>\n\n\n\n Similarly, the If you are using the reverse proxy approach, serve these files directly from the proxy to ensure consistency.<\/p>\n\n\n\n During parallel running, monitor both platforms to compare performance and catch issues.<\/p>\n\n\n\nWhy Parallel Running<\/h2>\n\n\n\n
\n
Architecture: Two Platforms, One Domain<\/h2>\n\n\n\n
Option 1: DNS-Based Routing<\/h3>\n\n\n\n
Phase 1: links.yourapp.com \u2192 old platform (100%)\nPhase 2: links.yourapp.com \u2192 new platform (100%)\n<\/code><\/pre>\n\n\n\nOption 2: Reverse Proxy Routing<\/h3>\n\n\n\n
User \u2192 links.yourapp.com \u2192 Reverse Proxy\n \u251c\u2192 Old Platform (for existing links)\n \u2514\u2192 New Platform (for new links)\n<\/code><\/pre>\n\n\n\n# Nginx: route by path prefix\nlocation \/new\/ {\n proxy_pass https:\/\/new-platform.example.com;\n}\n\nlocation \/ {\n proxy_pass https:\/\/old-platform.example.com;\n}\n<\/code><\/pre>\n\n\n\n\/new\/<\/code>) while existing links continue to work on the old platform.<\/p>\n\n\n\nOption 3: Percentage-Based Traffic Splitting<\/h3>\n\n\n\n
\/\/ Cloudflare Worker: percentage-based routing\naddEventListener('fetch', event => {\n event.respondWith(handleRequest(event.request));\n});\n\nasync function handleRequest(request) {\n const url = new URL(request.url);\n\n \/\/ Route new links (created on new platform) to new platform\n if (isNewPlatformLink(url.pathname)) {\n return fetch(`https:\/\/new-platform.example.com${url.pathname}${url.search}`, {\n headers: request.headers,\n });\n }\n\n \/\/ Route existing links to old platform\n return fetch(`https:\/\/old-platform.example.com${url.pathname}${url.search}`, {\n headers: request.headers,\n });\n}\n\nfunction isNewPlatformLink(path) {\n \/\/ Check against a list of paths created on the new platform\n \/\/ or use a naming convention\n return path.startsWith('\/v2\/') || newPlatformPaths.has(path);\n}\n<\/code><\/pre>\n\n\n\nSDK Coexistence<\/h2>\n\n\n\n
The Conflict Points<\/h3>\n\n\n\n
\n
iOS: SceneDelegate Configuration<\/h3>\n\n\n\n
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {\n guard let url = userActivity.webpageURL else { return }\n\n \/\/ New platform handles links with the new path structure\n if isNewPlatformLink(url) {\n TolinkuSDK.handleUniversalLink(url) { result in\n self.routeDeepLink(result)\n }\n return\n }\n\n \/\/ Old platform handles legacy links\n OldPlatformSDK.handleUniversalLink(url) { result in\n self.routeDeepLink(result)\n }\n}\n\nfunc isNewPlatformLink(_ url: URL) -> Bool {\n \/\/ Links created on the new platform use a specific path pattern\n return url.path.hasPrefix("\/v2\/") || newPlatformPaths.contains(url.path)\n}\n<\/code><\/pre>\n\n\n\nAndroid: Intent Filter Priority<\/h3>\n\n\n\n
class DeepLinkActivity : AppCompatActivity() {\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n\n val uri = intent.data ?: return\n\n if (isNewPlatformLink(uri)) {\n TolinkuSDK.handleDeepLink(uri) { result ->\n routeDeepLink(result)\n }\n } else {\n OldPlatformSDK.handleDeepLink(uri) { result ->\n routeDeepLink(result)\n }\n }\n }\n\n private fun isNewPlatformLink(uri: Uri): Boolean {\n return uri.path?.startsWith("\/v2\/") == true ||\n newPlatformPaths.contains(uri.path)\n }\n}\n<\/code><\/pre>\n\n\n\nInstall Referrer Handling<\/h3>\n\n\n\n
\/\/ Application.onCreate()\n\/\/ New SDK reads Install Referrer first\nTolinkuSDK.initialize(this, config = TolinkuConfig(\n readInstallReferrer = true\n))\n\n\/\/ Old SDK: disable Install Referrer reading\nOldPlatformSDK.initialize(this, config = OldConfig(\n readInstallReferrer = false,\n attributionOnly = true\n))\n<\/code><\/pre>\n\n\n\nVerification Files During Parallel Running<\/h2>\n\n\n\n
\/.well-known\/<\/code> paths, you need to merge the verification files.<\/p>\n\n\n\nMerging apple-app-site-association<\/h3>\n\n\n\n
applinks<\/code> entries. Merge the entries from both platforms:<\/p>\n\n\n\n{\n "applinks": {\n "apps": [],\n "details": [\n {\n "appIDs": ["TEAMID.com.yourapp.ios"],\n "components": [\n { "\/": "\/v2\/*" },\n { "\/": "\/*" }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nMerging assetlinks.json<\/h3>\n\n\n\n
assetlinks.json<\/code> file contains your app's package name and signing certificate, which are the same regardless of platform:<\/p>\n\n\n\n[\n {\n "relation": ["delegate_permission\/common.handle_all_urls"],\n "target": {\n "namespace": "android_app",\n "package_name": "com.yourapp.android",\n "sha256_cert_fingerprints": [\n "YOUR_SHA256_FINGERPRINT"\n ]\n }\n }\n]\n<\/code><\/pre>\n\n\n\nMonitoring Parallel Operation<\/h2>\n\n\n\n
Key Metrics to Compare<\/h3>\n\n\n\n