How Does Deep Linking Work? Complete Technical Guide (2026)

How Does Deep Linking Work? Complete Technical Guide (2026)

Deep linking works by matching a tapped URL to a screen registered inside an app: the operating system checks a server-hosted file to confirm the app owns that domain, hands the URL to the app, and the app's router parses it to navigate to the matching screen. If no app is installed, the link falls back to a browser or an app store listing.

That is the short answer. The rest of this guide breaks down the mechanism layer by layer: the exact handshake between your server and the OS, working iOS and Android handler code, how to check your setup with a deep link validator before you ship, and the configuration mistakes that break links in production even when the app code itself is correct.

How does deep linking work, step by step?

Deep linking works through five sequential checks: a tap, an OS lookup against registered domains or schemes, a verification step against a hosted association file, a handoff of the URL to the app process, and an in-app routing decision. A failure at any single step looks identical from the outside, the link "just doesn't work", which is why debugging it means checking each layer in order rather than guessing at app code.

Code
User taps link (SMS, email, ad, social post)
        |
        v
OS checks registered domains / URI schemes
        |
   match found? --- No ---> fallback to App Store / Play Store or web
        |
       Yes
        |
        v
OS validates association file (AASA on iOS, assetlinks.json on Android)
        |
        v
App receives URL via handler
  (iOS: continue userActivity, Android: Intent / onNewIntent)
        |
        v
App router parses path + query, navigates to matching screen
  1. Tap: the user clicks a link in a message, email, ad, or push notification.
  2. OS lookup: iOS and Android each check whether any installed app has registered that domain or scheme.
  3. Verification: iOS downloads your apple-app-site-association file at install time and caches the result; Android checks assetlinks.json at install and can re-verify at runtime.
  4. Handoff: if verification passed, the OS calls your app's link-handling method and passes the URL object.
  5. Routing: your app's router parses the path and parameters and navigates, or falls back to a store listing or browser if no app matched.

A standard deep link uses a custom URI scheme and only works if the app is already installed. A universal link or app link uses your real domain and falls back to the web when the app is missing. A deferred deep link preserves the intended destination through an app store install so the correct screen still opens on first launch.

TypeWorks without app installed?Trust signalBest for
URI Schemes (e.g. myapp://product/123)No, fails silently or errorsLow, looks like a custom protocolInternal app-to-app links, notifications
Universal Links (iOS) / App Links (Android)Yes, falls back to webHigh, uses your real domainMarketing, SMS, email, ads
Deferred Deep LinksYes, preserves destination through installHigh, feels seamless post-installPaid acquisition, referrals

The difference is not just technical, it is about user trust. Universal and App Links use your actual domain, so users see a real URL they recognize instead of a custom scheme that can look suspicious. If you are new to the concept entirely, our guide to what deep linking is covers the basics before you get into implementation.

How do I implement iOS app deep linking?

iOS app deep linking implementation needs four pieces working together: an apple-app-site-association file hosted at your domain's /.well-known/ path, an Associated Domains entitlement in Xcode, a handler for continue userActivity in your AppDelegate, and a router that parses the URL and navigates. Skipping or misconfiguring any one of these breaks the link silently.

  1. Host the association file. Serve apple-app-site-association at https://yourdomain.com/.well-known/apple-app-site-association with an application/json content-type, no redirects, and no added extension.
  2. Add the Associated Domains capability. In Xcode, add entries like applinks:yourdomain.com so iOS knows your app wants to handle links from that domain.
  3. Implement the runtime handler. iOS calls application(_:continue:restorationHandler:) with an NSUserActivity containing the URL when a matching link is tapped.
  4. Route internally. Parse the URL's path and query parameters and hand them to a dedicated router rather than navigating directly from the AppDelegate.
Swift
func application(_ app: UIApplication, continue userActivity: NSUserActivity,
                  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else { return false }

  let result = DeepLinkRouter.shared.route(url: url)
  switch result {
  case .navigate(let screen): AppNavigator.shared.present(screen)
  case .invalid: AppNavigator.shared.presentHome()
  }
  return true
}

For a deeper walkthrough of the manifest-side setup, see our full iOS Universal Links guide, and for the install-side handoff, our Swift guide to integrating deferred deep links walks through reading matched parameters on first launch.

How do I implement deferred deep linking on Android?

Deferred deep linking Android implementation works by recording a click's intended destination before the Play Store install happens, then matching that install to the click using the Play Install Referrer API or a deep linking platform, and reading the matched parameters in onCreate() so the correct screen opens on the very first launch.

  1. Declare intent filters in AndroidManifest.xml for activities that should handle direct deep links, specifying scheme, host, and path patterns.
  2. Publish assetlinks.json at https://yourdomain.com/.well-known/assetlinks.json with your package name and SHA-256 certificate fingerprints, proving you control both the domain and the app.
  3. Capture referrer data on install using the Play Install Referrer API, or let a deferred deep linking service store and match the click for you.
  4. Read matched parameters on first launch, before showing the default home screen, and route the user with the same logic you use for direct links.
  5. Handle both paths in one router, since a single user can arrive through a direct app link today and a deferred link after a reinstall tomorrow.
Kotlin
override fun onNewIntent(intent: Intent) {
  super.onNewIntent(intent)
  intent.data?.let { uri ->
    val result = DeepLinkRouter.route(uri)
    when (result) {
      is RoutingResult.Navigate -> navController.navigate(result.destination)
      is RoutingResult.Invalid -> navController.navigate("home")
    }
  }
}

Our Android App Links guide covers the manifest and verification setup in detail, and the step-by-step Android deferred deep link integration guide walks through wiring the install-referrer matching into the flow above. Smler's own deferred deep link generation guide covers the setup from the link-creation side.

A deep link validator checks that your apple-app-site-association or assetlinks.json file is syntactically correct, reachable without redirects, and served with the right content type, before a real user's tap exposes the problem. It cannot guarantee runtime behavior, because iOS caches its own validation result separately from this check.

In practice, run a validator at three points: once when you first publish the association file, again every time a deploy touches your /.well-known/ path or CDN rules, and once more whenever you add a new path pattern. Apple's AASA validator and Android's adb shell pm verify-app-links command cover the platform-level checks. Deep linking platforms like Smler allow you to verify your configuration by visiting the respective URLs to ensure the files are set up correctly.

Most deep linking failures happen not in your app code, but in the infrastructure and configuration layers teams treat as "set and forget" once launch is done.

SymptomLikely causeFix
Links worked, then stopped after a deployAssociation file behind a redirect or movedServe directly from canonical domain, no redirects, no extra headers
Works on some devices, not othersiOS cached an old or failed AASA validationReinstall the app or wait for the cache to refresh; check with Apple's AASA validator first
Works in staging, fails in productionCDN modifies content-type or adds security headersExclude /.well-known/* from CDN redirect and header rules
Some paths route correctly, others don'tCase-sensitive path mismatchNormalize URL paths to lowercase during parsing
Wrong mini-experience opens instead of the appApp Clip or Instant App intercepting the URLScope App Clip or Instant App invocation URLs narrowly

Redirect chains and CDN interference

If your AASA or assetlinks.json file sits behind HTTP redirects, common with www-to-non-www or HTTPS-enforcement rules, iOS will reject it outright, and Android can misbehave too. Association files must be served directly from the canonical domain with no redirects and no added extension. CDNs often make this worse by caching the file with the wrong content-type or adding security headers during an "always use HTTPS" rule; exclude /.well-known/* from any redirect or header rewrite rule.

Case sensitivity and app conflicts

iOS URL routing is case-sensitive by default, so if your backend treats /Product/123 and /product/123 as the same resource but your app expects lowercase, navigation fails. Normalize paths to lowercase during parsing. Separately, iOS App Clips and Android Instant Apps can intercept links you expect to go to your full app; scope their invocation URLs narrowly so they do not quietly swallow traffic meant for the installed app.

When an iOS user shares a link to an Android user, platform-specific parameters can confuse the receiving app if your URL structure was never designed to be platform-agnostic. Use query parameters both platforms can parse safely while ignoring the ones they do not recognize. Our App Links vs Universal Links comparison breaks down exactly where the two platforms diverge in practice.

The best practice is to never parse URLs and call navigation methods directly from your AppDelegate or Activity. Instead, build a dedicated router class that owns parsing, validation, and navigation decisions, so logging, edge cases, and routing changes do not require touching platform-specific launch code.

Swift
// Good: centralized routing
class DeepLinkRouter {
  func route(url: URL, context: AppContext) -> RoutingResult {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
    else { return .invalid(reason: "Malformed URL") }
    // validation, authentication checks, logging, then route to a screen
  }
}

// Bad: direct navigation from AppDelegate
func application(_ app: UIApplication, continue userActivity: NSUserActivity) {
  if let url = userActivity.webpageURL {
    // complex navigation logic buried here
  }
}

Graceful degradation and versioning

Every deep link needs a fallback for when the target content no longer exists, the user is not authenticated, or a feature is unavailable. Route to the closest meaningful destination instead of an error screen, if a product is deleted, show the category page; if login is required, save the destination and redirect after authentication. As your navigation structure evolves, version your URL patterns (/v2/product/123) so old links shared in emails, social posts, or indexed by search engines keep working.

Monitor and secure the handlers

Track link resolution time, failure rate by pattern, deferred deep link attribution accuracy, and platform-specific success rates separately from general app analytics. A sudden drop in Android success rate usually means a broken assetlinks.json after a deploy, and it stays invisible without dedicated monitoring. Deep links are also an attack surface: validate permissions before showing sensitive content, never trust URL parameters for authentication decisions, and require explicit confirmation before a deep link completes a payment or any irreversible action.

When should I avoid deep linking?

Deep linking is the wrong tool when the destination content is too personalized to make sense for a second viewer, when the flow depends on state built up across several prior screens, or when the web experience is genuinely better than forcing a user into the app.

Personalized content and multi-step flows

A link to "your recommendations" or "nearby results" based on GPS will not work meaningfully once shared with someone else. Likewise, deep linking directly into step three of a five-step checkout usually breaks, since that step depends on state from the steps before it. Link to the start of the flow instead, with parameters that prepopulate forms or skip irrelevant steps.

When the web experience is better

Long-form articles, dense data tables, or content full of outbound links are often better consumed in a browser than forced into a native app. Device-based routing can help here, choosing between app and web intelligently instead of forcing one path for every visitor.

Key takeaways

Deep linking works by mapping a URL to app content through a verification step the OS trusts, then handing the result to your router. Universal Links and App Links use hosted association files to prove domain ownership and fall back cleanly to the web, while deferred deep links preserve that same destination through an install. Most failures sit in configuration, redirects, CDNs, and stale validation caches, not in your navigation code, which is exactly why a deep link validator earns its place before every deploy that touches your /.well-known/ files.

Frequently asked questions

What happens if the app isn't installed when a deep link is tapped?

Standard URI-scheme links fail silently. Universal links and app links detect the missing app and fall back to a browser page or the app's store listing instead. Deferred deep links go a step further: they record the intended destination before the install so the matching screen still opens the first time the app launches.

Why do universal links sometimes open in Safari instead of the app?

This happens when a user long-presses a link and chooses "Open" from the context menu, or opens it from inside Safari or certain WebViews. iOS treats that as a deliberate choice to view the web version. A long-press on the link, then "Open in [App Name]," resets it; developers cannot override this platform behavior.

How do I test deep links without deploying association files to production?

Use URI schemes (myapp://) during early development since they skip AASA validation, then serve the real association file from a public HTTPS staging subdomain once you are testing universal or app links. Android supports manual verification via adb shell am start -W -a android.intent.action.VIEW -d "https://yourdomain.link/your-short-link" com.yourpackage.name. Our iOS testing guide and Android testing guide cover device-specific steps.

What's the difference between a deep link and a deferred deep link?

A regular deep link only works if the app is already installed and the link is tapped directly. A deferred deep link survives an app store install: the click is recorded, matched to the install, and the original destination parameters are handed to the app on first open. See our full deep linking vs deferred deep linking comparison for the implementation details.

Should I build deep linking myself or use a platform like Smler?

Build it directly for simple universal links and app links that route to static in-app content, it is straightforward and gives full control. Use a platform such as Smler's deferred deep linking when you need attribution through an install, link-level analytics, or bulk campaign link management without maintaining that matching logic yourself.

Next in this guideWhat Is a Deep Link? Types & Examples for Mobile Apps