{"id":1900,"date":"2026-07-31T13:00:00","date_gmt":"2026-07-31T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1900"},"modified":"2026-03-07T03:50:19","modified_gmt":"2026-03-07T08:50:19","slug":"deep-linking-multi-platform-teams","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/deep-linking-multi-platform-teams\/","title":{"rendered":"Deep Linking for Multi-Platform Engineering Teams"},"content":{"rendered":"\n

Deep linking touches every platform your app runs on. The AASA file is an iOS concern. The assetlinks.json is an Android concern. The Intent filters are in AndroidManifest.xml. The route handling might be in Swift, Kotlin, TypeScript, and Dart. When these pieces get out of sync, links break. This article covers how multi-platform teams coordinate deep link implementation.<\/p>\n\n\n\n

For shared routing patterns, see cross-platform link handling patterns<\/a>. For the cross-platform overview, see cross-platform deep linking guide for 2026<\/a>.<\/p>\n\n\n\n

The Coordination Problem<\/h2>\n\n\n\n

A single deep link route (e.g., \/products\/:productId<\/code>) requires changes in up to six places:<\/p>\n\n\n\n

    \n
  1. AASA file<\/strong> (hosted on your domain, for iOS)<\/li>\n
  2. assetlinks.json<\/strong> (hosted on your domain, for Android)<\/li>\n
  3. iOS entitlements<\/strong> (Associated Domains in Xcode)<\/li>\n
  4. AndroidManifest.xml<\/strong> (Intent filter with path prefix)<\/li>\n
  5. Client-side router<\/strong> (iOS, Android, and\/or cross-platform framework)<\/li>\n
  6. Server-side fallback<\/strong> (for users without the app)<\/li>\n<\/ol>\n\n\n\n

    If the iOS team adds a route to the AASA but the Android team forgets the Intent filter, the link works on iOS but not Android. If the backend team changes the server-side redirect but the mobile teams do not update the router, the app opens but shows the wrong screen.<\/p>\n\n\n\n

    Single Source of Truth<\/h2>\n\n\n\n

    Define all deep link routes in one place. Every team reads from this source.<\/p>\n\n\n\n

    Route Configuration File<\/h3>\n\n\n\n
    # deep-links.yaml\nroutes:\n  - path: "\/products\/{productId}"\n    screen: "ProductDetail"\n    platforms: [ios, android, web]\n    params:\n      productId:\n        type: string\n        required: true\n    queryParams:\n      ref:\n        type: string\n        required: false\n      campaign:\n        type: string\n        required: false\n\n  - path: "\/offers\/{offerId}"\n    screen: "OfferDetail"\n    platforms: [ios, android, web]\n    params:\n      offerId:\n        type: string\n        required: true\n\n  - path: "\/referral\/{referrerId}"\n    screen: "Referral"\n    platforms: [ios, android, web]\n    params:\n      referrerId:\n        type: string\n        required: true\n\n  - path: "\/ar-preview\/{productId}"\n    screen: "ARPreview"\n    platforms: [ios]  # ARKit only\n    params:\n      productId:\n        type: string\n        required: true\n    fallback:\n      screen: "ProductDetail"\n<\/code><\/pre>\n\n\n\n
    Code Generation<\/h3>\n\n\n\n
    Generate platform-specific configuration from the shared definition:<\/p>\n\n\n\n
    \/\/ generate-deep-link-configs.ts\nimport { parse } from 'yaml';\nimport { readFileSync, writeFileSync } from 'fs';\n\nconst config = parse(readFileSync('deep-links.yaml', 'utf8'));\n\nfunction generateAASA(routes: Route[]) {\n  const iosRoutes = routes.filter(r => r.platforms.includes('ios'));\n  return {\n    applinks: {\n      details: [{\n        appIDs: [process.env.APPLE_APP_ID],\n        components: iosRoutes.map(r => ({\n          '\/': r.path.replace(\/\\{[^}]+\\}\/g, '*')\n        }))\n      }]\n    }\n  };\n}\n\nfunction generateIntentFilters(routes: Route[]) {\n  const androidRoutes = routes.filter(r => r.platforms.includes('android'));\n  const prefixes = new Set(\n    androidRoutes.map(r => '\/' + r.path.split('\/')[1])\n  );\n  return Array.from(prefixes);\n}\n\nfunction generateRouterTests(routes: Route[]) {\n  return routes.map(route => ({\n    testUrl: route.path.replace(\/\\{(\\w+)\\}\/g, 'test-$1'),\n    expectedScreen: route.screen,\n    expectedParams: Object.keys(route.params).reduce((acc, key) => {\n      acc[key] = `test-${key}`;\n      return acc;\n    }, {} as Record<string, string>)\n  }));\n}\n<\/code><\/pre>\n\n\n\n
    Run this generator in CI to verify that platform configs match the source of truth.<\/p>\n\n\n\n
    Team Responsibilities<\/h2>\n\n\n\n
    Who Owns What<\/h3>\n\n\n\n
    \n\n\n\n\n\n\n\n\n\n
    Component<\/th>\nOwner<\/th>\nReview Required From<\/th>\n<\/tr>\n<\/thead>\n
    deep-links.yaml<\/code><\/td>\nProduct\/Engineering lead<\/td>\nAll platform teams<\/td>\n<\/tr>\n
    AASA file<\/td>\nBackend\/DevOps<\/td>\niOS team<\/td>\n<\/tr>\n
    assetlinks.json<\/td>\nBackend\/DevOps<\/td>\nAndroid team<\/td>\n<\/tr>\n
    iOS entitlements<\/td>\niOS team<\/td>\n–<\/td>\n<\/tr>\n
    AndroidManifest.xml<\/td>\nAndroid team<\/td>\n–<\/td>\n<\/tr>\n
    Client-side routing<\/td>\nEach platform team<\/td>\n–<\/td>\n<\/tr>\n
    Server-side fallback<\/td>\nBackend team<\/td>\nProduct<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
    Change Process<\/h3>\n\n\n\n
    When adding a new deep link route:<\/p>\n\n\n\n
      \n
    1. Proposal<\/strong>: Add the route to deep-links.yaml<\/code> in a PR. Tag all platform teams for review.<\/li>\n
    2. Backend<\/strong>: Deploy AASA and assetlinks.json updates. These must go live before the app update.<\/li>\n
    3. iOS<\/strong>: Add the route to the iOS router. Update entitlements if the domain changed.<\/li>\n
    4. Android<\/strong>: Add the Intent filter. Update the Android router.<\/li>\n
    5. Web<\/strong>: Add the server-side fallback route.<\/li>\n
    6. QA<\/strong>: Test on all platforms before release.<\/li>\n<\/ol>\n\n\n\n
      The AASA and assetlinks.json updates must be deployed first because iOS and Android cache these files. If the app ships with a new route but the verification files have not been updated, the links will not work until the cache refreshes (up to 24 hours on iOS, variable on Android).<\/p>\n\n\n\n
      Shared Testing<\/h2>\n\n\n\n
      Contract Tests<\/h3>\n\n\n\n
      Write tests that verify each platform's router handles the same URLs consistently:<\/p>\n\n\n\n
      \/\/ shared-deep-link-tests.json\n{\n  "tests": [\n    {\n      "url": "https:\/\/yourdomain.com\/products\/abc123",\n      "expectedScreen": "ProductDetail",\n      "expectedParams": { "productId": "abc123" }\n    },\n    {\n      "url": "https:\/\/yourdomain.com\/products\/abc123?ref=email&campaign=summer",\n      "expectedScreen": "ProductDetail",\n      "expectedParams": {\n        "productId": "abc123",\n        "ref": "email",\n        "campaign": "summer"\n      }\n    },\n    {\n      "url": "https:\/\/yourdomain.com\/offers\/deal456",\n      "expectedScreen": "OfferDetail",\n      "expectedParams": { "offerId": "deal456" }\n    },\n    {\n      "url": "https:\/\/yourdomain.com\/nonexistent\/path",\n      "expectedScreen": null,\n      "expectedParams": {}\n    }\n  ]\n}\n<\/code><\/pre>\n\n\n\n
      Each platform team writes a test runner that reads this file and verifies their router:<\/p>\n\n\n\n
      iOS (XCTest)<\/strong>:<\/p>\n\n\n\n
      func testSharedDeepLinkContracts() {\n    let tests = loadSharedTests()\n    for test in tests {\n        let result = DeepLinkRouter.match(url: test.url)\n        XCTAssertEqual(result?.screen, test.expectedScreen)\n        XCTAssertEqual(result?.params, test.expectedParams)\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Android (JUnit)<\/strong>:<\/p>\n\n\n\n
      @Test\nfun `shared deep link contracts`() {\n    val tests = loadSharedTests()\n    tests.forEach { test ->\n        val result = DeepLinkRouter.match(test.url)\n        assertEquals(test.expectedScreen, result?.screen)\n        assertEquals(test.expectedParams, result?.params)\n    }\n}\n<\/code><\/pre>\n\n\n\n
      End-to-End Testing<\/h3>\n\n\n\n
      Run E2E tests on each platform in CI:<\/p>\n\n\n\n
      # iOS (Xcode Cloud or Bitrise)\nxcrun simctl openurl booted "https:\/\/yourdomain.com\/products\/abc123"\n# Assert the ProductDetail screen is visible\n\n# Android (Firebase Test Lab)\nadb shell am start -a android.intent.action.VIEW \\\n  -d "https:\/\/yourdomain.com\/products\/abc123" \\\n  -c android.intent.category.BROWSABLE\n# Assert the ProductDetail screen is visible\n<\/code><\/pre>\n\n\n\n
      Versioning Deep Links<\/h2>\n\n\n\n
      When a deep link path changes, you need backward compatibility. Old links shared via email, social media, or QR codes may circulate indefinitely.<\/p>\n\n\n\n
      Server-Side Redirects<\/h3>\n\n\n\n
      Handle deprecated paths with server-side redirects:<\/p>\n\n\n\n
      \/\/ Redirect old paths to new ones\nconst redirects: Record<string, string> = {\n  '\/item\/': '\/products\/',     \/\/ Old path format\n  '\/deal\/': '\/offers\/',       \/\/ Renamed route\n  '\/invite\/': '\/referral\/'    \/\/ Renamed route\n};\n\napp.use((req, res, next) => {\n  for (const [oldPrefix, newPrefix] of Object.entries(redirects)) {\n    if (req.path.startsWith(oldPrefix)) {\n      const newPath = req.path.replace(oldPrefix, newPrefix);\n      res.redirect(301, newPath + (req.originalUrl.includes('?')\n        ? '?' + req.originalUrl.split('?')[1]\n        : ''));\n      return;\n    }\n  }\n  next();\n});\n<\/code><\/pre>\n\n\n\n
      Client-Side Compatibility<\/h3>\n\n\n\n
      Keep old routes in the client router for at least two release cycles:<\/p>\n\n\n\n
      function matchRoute(url: string): RouteMatch | null {\n  \/\/ Current routes\n  const currentMatch = matchCurrentRoutes(url);\n  if (currentMatch) return currentMatch;\n\n  \/\/ Legacy routes (remove after v3.0)\n  const legacyMatch = matchLegacyRoutes(url);\n  if (legacyMatch) {\n    analytics.track('legacy_deep_link', { url });\n    return legacyMatch;\n  }\n\n  return null;\n}\n<\/code><\/pre>\n\n\n\n
      Monitoring<\/h2>\n\n\n\n
      Track deep link health across platforms:<\/p>\n\n\n\n
      \/\/ Log every deep link attempt\nfunction trackDeepLink(url: string, result: 'matched' | 'unmatched', platform: string) {\n  analytics.track('deep_link_received', {\n    url,\n    result,\n    platform,\n    screen: result === 'matched' ? matchedScreen : null,\n    timestamp: Date.now()\n  });\n}\n<\/code><\/pre>\n\n\n\n
      Set up alerts for:<\/p>\n\n\n\n