{"id":1848,"date":"2026-07-25T17:00:00","date_gmt":"2026-07-25T22:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1848"},"modified":"2026-03-07T03:50:12","modified_gmt":"2026-03-07T08:50:12","slug":"deep-linking-lifecycle","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/deep-linking-lifecycle\/","title":{"rendered":"The Deep Linking Lifecycle: From Click to Content"},"content":{"rendered":"\n

A deep link click triggers a chain of events across the browser, operating system, app store, and your app. Each step can succeed or fail, and failures at different stages produce different user experiences. Understanding the full lifecycle helps you debug issues and optimize each transition.<\/p>\n\n\n\n

For the technical overview, see how deep linking works: a technical overview<\/a>. For routing specifics, see deep link routing: how to route users to the right screen<\/a>.<\/p>\n\n\n\n

The Full Lifecycle<\/h2>\n\n\n\n
1. User taps a link\n   \u2193\n2. Browser\/OS intercepts the URL\n   \u2193\n3. OS checks domain verification (AASA \/ assetlinks.json)\n   \u251c\u2500\u2500 Verified \u2192 4a. OS launches the app\n   \u2514\u2500\u2500 Not verified \u2192 4b. Browser loads the URL\n   \u2193\n4a. App receives the URL\n   \u2193\n5. App routes to the correct screen\n   \u2193\n6. Screen loads with the correct content\n   \u2193\n7. Analytics event fires\n<\/code><\/pre>\n\n\n\n
Each stage has its own failure modes, timing constraints, and optimization opportunities.<\/p>\n\n\n\n
Stage 1: The Click<\/h2>\n\n\n\n
Where the Click Happens<\/h3>\n\n\n\n
The user's context when they tap the link determines what happens next:<\/p>\n\n\n\n
\n\n\n\n\n\n\n\n\n\n
Context<\/th>\nWhat Happens<\/th>\n<\/tr>\n<\/thead>\n
System browser (Safari, Chrome)<\/td>\nUniversal Links \/ App Links activate normally<\/td>\n<\/tr>\n
In-app browser (Facebook, Instagram)<\/td>\nUniversal Links are blocked; App Links may work<\/td>\n<\/tr>\n
Email client (Gmail app)<\/td>\nOften opens in-app browser first<\/td>\n<\/tr>\n
Push notification<\/td>\nApp is already the handler; no browser involved<\/td>\n<\/tr>\n
QR code scan<\/td>\nCamera app opens system browser<\/td>\n<\/tr>\n
SMS\/iMessage<\/td>\nLinks open in system browser<\/td>\n<\/tr>\n
Desktop browser<\/td>\nNo app to open; web fallback<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
Click Recording<\/h3>\n\n\n\n
If you are using a deep link platform, the click is recorded server-side before any redirection:<\/p>\n\n\n\n
async function handleClick(req: Request): Promise<Response> {\n  const clickId = generateClickId();\n  const startTime = Date.now();\n\n  \/\/ Record the click\n  await analytics.recordClick({\n    clickId,\n    timestamp: new Date(),\n    url: req.url,\n    ip: req.ip,\n    userAgent: req.headers['user-agent'],\n    referrer: req.headers['referer'],\n    route: parseRoute(req.url)\n  });\n\n  \/\/ Determine the response (redirect, render, etc.)\n  const response = await resolveLink(req);\n\n  \/\/ Record latency\n  await analytics.updateClick(clickId, {\n    latencyMs: Date.now() - startTime,\n    outcome: response.type \/\/ 'app_opened', 'fallback', 'store_redirect'\n  });\n\n  return response;\n}\n<\/code><\/pre>\n\n\n\n
Stage 2: OS Interception<\/h2>\n\n\n\n
iOS (Universal Links)<\/h3>\n\n\n\n
When the user taps an HTTPS link:<\/p>\n\n\n\n
    \n
  1. iOS checks its local cache of AASA files.<\/li>\n
  2. If the domain is in the cache and the URL path matches an applinks<\/code> entry, iOS opens the registered app.<\/li>\n
  3. If the domain is not cached, iOS fetches the AASA file from Apple's CDN (not directly from your server on iOS 14+).<\/li>\n
  4. If the AASA is invalid, missing, or the path does not match, Safari opens the URL normally.<\/li>\n<\/ol>\n\n\n\n
    Timing:<\/strong> The AASA lookup is nearly instant (cached locally). The initial download from Apple's CDN happens during app installation, not at click time.<\/p>\n\n\n\n
    Key detail:<\/strong> If the user long-presses a Universal Link and sees "Open in Safari" and "Open in [App]," they can choose to open in Safari. Once they do this, iOS remembers the preference and subsequent taps on that domain open in Safari. The user must long-press again and choose "Open in [App]" to restore the behavior.<\/p>\n\n\n\n
    Android (App Links)<\/h3>\n\n\n\n
    When the user taps an HTTPS link:<\/p>\n\n\n\n
      \n
    1. Android checks if any installed app has a verified App Link for this domain.<\/li>\n
    2. If verified (autoVerify="true"<\/code> in the manifest and assetlinks.json<\/code> validates), the app opens automatically.<\/li>\n
    3. If not verified, Android shows a disambiguation dialog ("Open with: Chrome or [App]").<\/li>\n
    4. If no app handles the URL, Chrome opens the URL normally.<\/li>\n<\/ol>\n\n\n\n
      Timing:<\/strong> Verification happens at install time and periodically (Android 12+). The click-time check is instant.<\/p>\n\n\n\n
      Stage 3: Verification<\/h2>\n\n\n\n
      AASA Verification (iOS)<\/h3>\n\n\n\n
      App installed\n  \u2193\niOS fetches AASA from Apple's CDN\n  \u2193\nCDN checks your server: GET \/.well-known\/apple-app-site-association\n  \u2193\nServer returns JSON with applinks\n  \u2193\niOS caches the AASA locally\n  \u2193\nAll future link taps check the local cache\n<\/code><\/pre>\n\n\n\n
      If the AASA is not available when the app is installed, Universal Links will not work until the cache is refreshed (up to 24 hours or on app reinstall).<\/p>\n\n\n\n
      assetlinks.json Verification (Android)<\/h3>\n\n\n\n
      App installed\n  \u2193\nAndroid fetches \/.well-known\/assetlinks.json from your server\n  \u2193\nVerifies: package name matches, SHA-256 fingerprint matches\n  \u2193\nMarks the domain as "verified" for this app\n  \u2193\nAll future link taps open the app directly (no dialog)\n<\/code><\/pre>\n\n\n\n
      On Android 12+, re-verification happens periodically. If assetlinks.json<\/code> is unavailable during re-verification, the domain may become "unverified."<\/p>\n\n\n\n
      Stage 4: App Launch or Fallback<\/h2>\n\n\n\n
      App Opens (Happy Path)<\/h3>\n\n\n\n
      The OS launches the app and passes the URL:<\/p>\n\n\n\n
      iOS:<\/strong><\/p>\n\n\n\n
      \/\/ Scene delegate (iOS 13+)\nfunc scene(_ scene: UIScene, continue userActivity: NSUserActivity) {\n    guard let url = userActivity.webpageURL else { return }\n    handleDeepLink(url)\n}\n\n\/\/ SwiftUI\n.onOpenURL { url in\n    handleDeepLink(url)\n}\n<\/code><\/pre>\n\n\n\n
      Android:<\/strong><\/p>\n\n\n\n
      override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    val url = intent.data\n    if (url != null) {\n        handleDeepLink(url)\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Fallback (App Not Installed or Verification Failed)<\/h3>\n\n\n\n
      If the app does not open, the browser loads the URL. Your server should detect this and serve an appropriate fallback:<\/p>\n\n\n\n
      app.get('\/products\/:id', (req, res) => {\n  const userAgent = req.headers['user-agent'] || '';\n\n  if (isIOS(userAgent)) {\n    \/\/ Show web content + smart banner to install the app\n    res.render('product-fallback', {\n      product: getProduct(req.params.id),\n      appStoreUrl: 'https:\/\/apps.apple.com\/app\/id123456',\n      deepLink: req.url\n    });\n  } else if (isAndroid(userAgent)) {\n    \/\/ Same, with Play Store link\n    res.render('product-fallback', {\n      product: getProduct(req.params.id),\n      playStoreUrl: 'https:\/\/play.google.com\/store\/apps\/details?id=com.example.app',\n      deepLink: req.url\n    });\n  } else {\n    \/\/ Desktop: full web experience\n    res.render('product', { product: getProduct(req.params.id) });\n  }\n});\n<\/code><\/pre>\n\n\n\n
      Stage 5: Routing<\/h2>\n\n\n\n
      Once the app receives the URL, it must route to the correct screen:<\/p>\n\n\n\n
      function routeDeepLink(url: URL): Screen {\n  const path = url.pathname;\n  const params = Object.fromEntries(url.searchParams);\n\n  \/\/ Match routes in order of specificity\n  const routes = [\n    { pattern: \/^\\\/products\\\/([^\/]+)$\/, screen: 'ProductDetail', extract: ['productId'] },\n    { pattern: \/^\\\/offers\\\/([^\/]+)$\/, screen: 'OfferDetail', extract: ['offerId'] },\n    { pattern: \/^\\\/users\\\/([^\/]+)\\\/posts\\\/([^\/]+)$\/, screen: 'Post', extract: ['userId', 'postId'] },\n    { pattern: \/^\\\/referral\\\/([^\/]+)$\/, screen: 'Referral', extract: ['referrerId'] },\n    { pattern: \/^\\\/settings$\/, screen: 'Settings', extract: [] },\n  ];\n\n  for (const route of routes) {\n    const match = path.match(route.pattern);\n    if (match) {\n      const pathParams: Record<string, string> = {};\n      route.extract.forEach((name, i) => {\n        pathParams[name] = match[i + 1];\n      });\n      return { name: route.screen, pathParams, queryParams: params };\n    }\n  }\n\n  \/\/ No match: default to home screen\n  return { name: 'Home', pathParams: {}, queryParams: params };\n}\n<\/code><\/pre>\n\n\n\n
      Authentication-Gated Routes<\/h3>\n\n\n\n
      Some deep link routes require the user to be logged in:<\/p>\n\n\n\n
      func handleDeepLink(_ url: URL) {\n    let route = routeDeepLink(url)\n\n    if route.requiresAuth && !user.isLoggedIn {\n        \/\/ Save the deep link for after login\n        pendingDeepLink = url\n        showLoginScreen()\n    } else {\n        navigateTo(route)\n    }\n}\n\nfunc onLoginSuccess() {\n    if let pending = pendingDeepLink {\n        handleDeepLink(pending)\n        pendingDeepLink = nil\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Stage 6: Content Loading<\/h2>\n\n\n\n
      The screen needs to load the correct content based on the deep link parameters:<\/p>\n\n\n\n
      class ProductViewController: UIViewController {\n    let productId: String\n\n    init(productId: String) {\n        self.productId = productId\n        super.init(nibName: nil, bundle: nil)\n    }\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n        loadProduct()\n    }\n\n    func loadProduct() {\n        showLoadingSpinner()\n\n        api.getProduct(id: productId) { [weak self] result in\n            switch result {\n            case .success(let product):\n                self?.displayProduct(product)\n            case .failure:\n                self?.showError("Product not found")\n            }\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Handle edge cases:<\/p>\n\n\n\n