Opening an app is the easy part. The hard part is getting users to the right place once they're inside.<\/p>\n\n\n\n
Deep link routing is the layer of logic that sits between receiving an incoming URL and presenting the correct screen to the user. Get it right and users land exactly where they expect. Get it wrong and they end up staring at a home screen with no idea where the content they were looking for went.<\/p>\n\n\n\n
This guide walks through the full picture: how to design a URL structure worth routing against, how to build a router that handles real-world complexity, and how to wire everything up on iOS and Android with concrete code examples.<\/p>\n\n\n\n
A lot of tutorials stop at "configure your app to handle the URL scheme." That covers the handoff from the operating system to your app, but nothing about what happens next.<\/p>\n\n\n\n
Consider a few scenarios your router will face in production:<\/p>\n\n\n\n
\/product\/12345<\/code> arrives while the user is three screens deep inside a settings flow<\/li>\n- A link to
\/order\/history<\/code> arrives but the user is not logged in<\/li>\n- A link to
\/promo\/SUMMER2026<\/code> contains a campaign parameter that needs to be tracked before navigating<\/li>\n- A link arrives for a route that no longer exists after a recent app update<\/li>\n
- A link arrives with a tampered or malicious payload that should be rejected (see our guide on deep linking security<\/a> for more on this)<\/li>\n<\/ul>\n\n\n\n
Each of these requires deliberate handling. A router that only knows how to match a path and push a view controller will fail on most of them.<\/p>\n\n\n\n
The goal of a proper routing layer is to:<\/p>\n\n\n\n
\n- Parse the incoming URL into a structured intent<\/li>\n
- Decide whether the user has the necessary state (authentication, onboarding completion, etc.) to fulfill that intent<\/li>\n
- Navigate to the correct screen, adjusting the navigation stack as needed<\/li>\n
- Fall back gracefully when fulfillment is not possible<\/li>\n<\/ol>\n\n\n\n
Designing a URL Structure Worth Routing Against<\/h2>\n\n\n\n
Before writing any router code, your URL structure needs to be consistent and predictable. A few rules that pay off over time:<\/p>\n\n\n\n
Keep resource paths shallow.<\/strong> \/product\/12345<\/code> is easier to match and extend than \/catalog\/products\/detail\/12345<\/code>. Nesting beyond two levels usually signals that you're encoding too much state in the URL.<\/p>\n\n\n\nSeparate resource identifiers from query parameters.<\/strong> Resource identity belongs in the path (\/order\/abc123<\/code>). Filters, campaign tokens, and display hints belong in query parameters (?ref=email&highlight=true<\/code>). This keeps your route definitions clean and makes parameter extraction predictable. For a detailed look at parameter naming conventions and best practices, see our deep link parameters guide<\/a>.<\/p>\n\n\n\nUse consistent ID formats.<\/strong> If some routes use numeric IDs and others use slugs, your router has to handle both. Pick one convention and apply it across the board.<\/p>\n\n\n\nVersion intentionally.<\/strong> You don't need \/v1\/product\/...<\/code> in deep link URLs, but you do need a plan for what happens when a route is deprecated. A redirect mapping table inside your router (old path to new path) is far easier to maintain than communicating URL changes to every channel where you've distributed links.<\/p>\n\n\n\nA solid URL structure for a typical e-commerce app might look like this:<\/p>\n\n\n\n
myapp:\/\/ \u2192 Home\nmyapp:\/\/product\/{id} \u2192 Product detail\nmyapp:\/\/category\/{slug} \u2192 Category listing\nmyapp:\/\/cart \u2192 Cart\nmyapp:\/\/order\/{id} \u2192 Order detail\nmyapp:\/\/account\/profile \u2192 User profile\nmyapp:\/\/account\/orders \u2192 Order history\nmyapp:\/\/promo\/{code} \u2192 Promo code redemption\n<\/code><\/pre>\n\n\n\nFor Universal Links and App Links, the same paths apply under your HTTPS domain:<\/p>\n\n\n\n
https:\/\/myapp.com\/product\/{id}\nhttps:\/\/myapp.com\/category\/{slug}\n<\/code><\/pre>\n\n\n\nTolinku's route configuration<\/a> lets you define these paths centrally and map them to behavior across platforms, which keeps your URL structure consistent even as your app evolves.<\/p>\n\n\n\nBuilding a Router: Pattern Matching and Parameter Extraction<\/h2>\n\n\n\n
A router at its core does two things: match a URL against a set of known patterns, and extract parameters from the match.<\/p>\n\n\n\n
Here is a minimal router in Swift that demonstrates both:<\/p>\n\n\n\n
struct Route {\n let pattern: String\n let handler: ([String: String], URLComponents) -> Void\n\n func matches(_ path: String) -> [String: String]? {\n let patternParts = pattern.split(separator: "\/")\n let pathParts = path.split(separator: "\/")\n\n guard patternParts.count == pathParts.count else { return nil }\n\n var params: [String: String] = [:]\n for (patternPart, pathPart) in zip(patternParts, pathParts) {\n if patternPart.hasPrefix(":") {\n let key = String(patternPart.dropFirst())\n params[key] = String(pathPart)\n } else if patternPart != pathPart {\n return nil\n }\n }\n return params\n }\n}\n\nclass AppRouter {\n private var routes: [Route] = []\n\n func register(pattern: String, handler: @escaping ([String: String], URLComponents) -> Void) {\n routes.append(Route(pattern: pattern, handler: handler))\n }\n\n func handle(url: URL) -> Bool {\n guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),\n let path = components.path.isEmpty ? "\/" : Optional(components.path) else {\n return false\n }\n\n for route in routes {\n if let params = route.matches(path) {\n route.handler(params, components)\n return true\n }\n }\n return false\n }\n}\n<\/code><\/pre>\n\n\n\nAnd the equivalent in Kotlin for Android:<\/p>\n\n\n\n
data class Route(\n val pattern: String,\n val handler: (Map<String, String>, Uri) -> Unit\n) {\n fun matches(path: String): Map<String, String>? {\n val patternParts = pattern.trim('\/').split("\/")\n val pathParts = path.trim('\/').split("\/")\n\n if (patternParts.size != pathParts.size) return null\n\n val params = mutableMapOf<String, String>()\n for ((patternPart, pathPart) in patternParts.zip(pathParts)) {\n when {\n patternPart.startsWith(":") -> params[patternPart.drop(1)] = pathPart\n patternPart != pathPart -> return null\n }\n }\n return params\n }\n}\n\nclass AppRouter {\n private val routes = mutableListOf<Route>()\n\n fun register(pattern: String, handler: (Map<String, String>, Uri) -> Unit) {\n routes.add(Route(pattern, handler))\n }\n\n fun handle(uri: Uri): Boolean {\n val path = uri.path ?: return false\n for (route in routes) {\n val params = route.matches(path) ?: continue\n route.handler(params, uri)\n return true\n }\n return false\n }\n}\n<\/code><\/pre>\n\n\n\nThe pattern :id<\/code> extracts the value at that position into a named parameter. Query parameters come from the URL components object and are handled separately, which keeps the matching logic simple.<\/p>\n\n\n\niOS Routing: AppDelegate, SceneDelegate, and the Coordinator Pattern<\/h2>\n\n\n\n
On iOS, deep links arrive in one of two places depending on how the user's device opened the URL:<\/p>\n\n\n\n
\napplication(_:open:options:)<\/code> in AppDelegate<\/code> for custom URL schemes<\/li>\nscene(_:continue:)<\/code> in SceneDelegate<\/code> for Universal Links arriving via NSUserActivity<\/code><\/li>\n<\/ul>\n\n\n\nBoth should funnel into the same router:<\/p>\n\n\n\n
\/\/ AppDelegate.swift\nfunc application(_ app: UIApplication, open url: URL,\n options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {\n return AppRouter.shared.handle(url: url)\n}\n\n\/\/ SceneDelegate.swift\nfunc scene(_ scene: UIScene, continue userActivity: NSUserActivity) {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let url = userActivity.webpageURL else { return }\n AppRouter.shared.handle(url: url)\n}\n\nfunc scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {\n guard let url = URLContexts.first?.url else { return }\n AppRouter.shared.handle(url: url)\n}\n<\/code><\/pre>\n\n\n\nFor navigation, the coordinator pattern works well with deep linking because it centralizes navigation decisions away from individual view controllers. Each coordinator knows how to display a particular section of your app and can accept a starting route.<\/p>\n\n\n\n
class ProductCoordinator {\n let navigationController: UINavigationController\n\n init(navigationController: UINavigationController) {\n self.navigationController = navigationController\n }\n\n func showProduct(id: String) {\n let vc = ProductViewController(productId: id)\n navigationController.pushViewController(vc, animated: true)\n }\n}\n\n\/\/ Register routes in your app setup\nAppRouter.shared.register(pattern: "\/product\/:id") { params, components in\n guard let id = params["id"] else { return }\n AppCoordinator.shared.showProduct(id: id)\n}\n<\/code><\/pre>\n\n\n\nOne thing to handle carefully: the link may arrive before the app has finished loading its root view controller, especially on cold launch. Queuing the pending route and fulfilling it after the app finishes initialization avoids race conditions:<\/p>\n\n\n\n
class AppRouter {\n var pendingURL: URL?\n\n func handle(url: URL) -> Bool {\n guard appIsReady else {\n pendingURL = url\n return true\n }\n return route(url: url)\n }\n\n func appDidBecomeReady() {\n if let url = pendingURL {\n pendingURL = nil\n _ = route(url: url)\n }\n }\n}\n<\/code><\/pre>\n\n\n\nAndroid Routing: Navigation Component and Deep Link Destinations<\/h2>\n\n\n\n
Android's Navigation component<\/a> has built-in deep link support through <deepLink><\/code> declarations in your navigation graph. For simple cases this handles routing for you. For more control, you can intercept the intent directly.<\/p>\n\n\n\nDeclare deep link destinations in your nav graph XML:<\/p>\n\n\n\n
<fragment\n android:id="@+id\/productFragment"\n android:name="com.myapp.ProductFragment"\n tools:layout="@layout\/fragment_product">\n <argument\n android:name="productId"\n app:argType="string" \/>\n <deepLink\n app:uri="myapp:\/\/product\/{productId}"\n app:action="android.intent.action.VIEW" \/>\n<\/fragment>\n<\/code><\/pre>\n\n\n\nFor Universal Links (App Links on Android), add the corresponding HTTPS URI:<\/p>\n\n\n\n
<deepLink\n app:uri="https:\/\/myapp.com\/product\/{productId}" \/>\n<\/code><\/pre>\n\n\n\nWhen you need custom routing logic (authentication checks, redirect mapping, analytics events on link arrival), handle the incoming intent before the Navigation component processes it:<\/p>\n\n\n\n
class MainActivity : AppCompatActivity() {\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n setContentView(R.layout.activity_main)\n\n if (savedInstanceState == null) {\n intent?.data?.let { uri ->\n if (!AppRouter.handle(uri, this)) {\n navigateToHome()\n }\n }\n }\n }\n\n override fun onNewIntent(intent: Intent?) {\n super.onNewIntent(intent)\n intent?.data?.let { uri ->\n AppRouter.handle(uri, this)\n }\n }\n}\n<\/code><\/pre>\n\n\n\nRegister routes once during application initialization:<\/p>\n\n\n\n
class MyApplication : Application() {\n override fun onCreate() {\n super.onCreate()\n\n AppRouter.register("\/product\/:id") { params, uri ->\n val id = params["id"] ?: return@register\n val intent = ProductActivity.newIntent(this, id)\n startActivity(intent)\n }\n\n AppRouter.register("\/account\/orders") { _, _ ->\n if (AuthManager.isLoggedIn()) {\n startActivity(OrderHistoryActivity.newIntent(this))\n } else {\n startActivity(LoginActivity.newIntentWithRedirect(this, "\/account\/orders"))\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\nHandling Unknown Routes Gracefully<\/h2>\n\n\n\n
Every router will eventually receive a URL it does not recognize. This happens when:<\/p>\n\n\n\n
\n- A user taps an old link after you have restructured your URL paths<\/li>\n
- A link is constructed incorrectly by a third-party integration<\/li>\n
- A route that existed in a previous version of the app is no longer present<\/li>\n<\/ul>\n\n\n\n
The worst response is a silent failure that lands the user on the home screen with no feedback. Our deep link fallback behavior guide<\/a> covers the full range of fallback strategies in detail. Better options, in order of preference:<\/p>\n\n\n\n\nRedirect to the closest equivalent.<\/strong> Keep a mapping of deprecated paths to their replacements inside your router. A \/v1\/product\/:id<\/code> to \/product\/:id<\/code> redirect table adds minimal maintenance burden and handles a lot of real-world cases.<\/p>\n\n\n\nFall through to web content.<\/strong> If your app has a web equivalent, open the URL in a browser or in-app browser instead of failing. The user gets the content they wanted, just not inside the app.<\/p>\n\n\n\nShow a contextual error screen.<\/strong> If you cannot redirect and web fallback is not appropriate, show a screen that acknowledges the failure and gives the user a clear path back into the app (home, search, or the section they were most likely trying to reach).<\/p>\n\n\n\n\/\/ Swift: fallback handler registered last\nAppRouter.shared.registerFallback { url in\n if let webURL = url.asWebURL {\n \/\/ open in SFSafariViewController\n presentSafariViewController(url: webURL)\n } else {\n navigateToHome()\n showToast("That link is no longer available.")\n }\n}\n<\/code><\/pre>\n\n\n\n\/\/ Kotlin: fallback in AppRouter.handle\nfun handle(uri: Uri, context: Context): Boolean {\n val path = uri.path ?: return false\n for (route in routes) {\n val params = route.matches(path) ?: continue\n route.handler(params, uri)\n return true\n }\n \/\/ Fallback: try web\n return tryOpenInBrowser(uri, context)\n}\n<\/code><\/pre>\n\n\n\nTesting Your Router<\/h2>\n\n\n\n
A router that works in development and breaks in production is worse than one with known gaps, because it fails silently in edge cases you did not think to test. For a roundup of tools that can help automate this process, see our deep link testing tools<\/a> article. A few practices that catch problems early:<\/p>\n\n\n\nUnit test pattern matching directly.<\/strong> The route matching logic is pure and deterministic, which makes it ideal for unit testing. Write test cases for exact matches, parameterized matches, mismatches on segment count, and mismatches on literal segments.<\/p>\n\n\n\nfunc testProductRouteMatches() {\n let route = Route(pattern: "\/product\/:id") { _, _ in }\n let params = route.matches("\/product\/abc123")\n XCTAssertEqual(params?["id"], "abc123")\n}\n\nfunc testProductRouteDoesNotMatchCategory() {\n let route = Route(pattern: "\/product\/:id") { _, _ in }\n XCTAssertNil(route.matches("\/category\/shoes"))\n}\n<\/code><\/pre>\n\n\n\nTest the full URL handling path.<\/strong> Pass complete URLs (including scheme, host, and query parameters) through the top-level handle<\/code> method to confirm that parsing and dispatch work end-to-end.<\/p>\n\n\n\nTest cold launch routing.<\/strong> Simulate the app receiving a deep link on a fresh launch in your UI tests. This is where the pending URL queue gets exercised and where timing bugs surface.<\/p>\n\n\n\nTest authentication guards.<\/strong> Confirm that routes requiring login redirect to login (with the intended destination preserved) rather than crashing or showing blank screens.<\/p>\n\n\n\n