Deep link handling requires platform-specific entry points (Universal Links on iOS, App Links on Android, URL routing on web) but the actual routing logic, the part that decides "this URL maps to this screen with these parameters," can be shared. This article covers patterns for writing link handling code once and adapting it per platform.<\/p>\n\n\n\n
For the complete cross-platform overview, see cross-platform deep linking guide for 2026<\/a>. For routing fundamentals, see deep link routing: how to route users to the right screen<\/a>.<\/p>\n\n\n\n Each platform has its own API for receiving deep links:<\/p>\n\n\n\n The URL arrives through different APIs, but the question is always the same: given this path and these query parameters, which screen should the user see?<\/p>\n\n\n\n Define routes in a platform-agnostic format. Each platform's entry point parses the URL and passes it through the shared table.<\/p>\n\n\n\n iOS (Swift)<\/strong>:<\/p>\n\n\n\n Android (Kotlin)<\/strong>:<\/p>\n\n\n\n Web<\/strong>:<\/p>\n\n\n\n Instead of mapping URLs directly to screens, map them to actions. This decouples the deep link layer from the navigation layer.<\/p>\n\n\n\n Each platform implements its own action handler:<\/p>\n\n\n\n This pattern is useful when some actions require side effects (storing a referral code, triggering an analytics event) before navigation.<\/p>\n\n\n\n For apps with many deep link paths, define routes in a configuration file that all platforms read:<\/p>\n\n\n\n A shared parser converts path patterns to regex:<\/p>\n\n\n\n This approach keeps route definitions in sync across platforms. If you add a new deep link path, update the config file once.<\/p>\n\n\n\n Even with shared routing logic, some behaviors differ between platforms.<\/p>\n\n\n\n When a deep link targets an authenticated screen, the behavior depends on platform conventions:<\/p>\n\n\n\n When a route does not match, each platform has a different fallback:<\/p>\n\n\n\nThe Problem<\/h2>\n\n\n\n
\n
application(_:continue:restorationHandler:)<\/code> in AppDelegate or SceneDelegate<\/li>\nACTION_VIEW<\/code> delivered to the Activity<\/li>\nwindow.location<\/code> parsed on page load<\/li>\nApp.addListener('appUrlOpen', ...)<\/code><\/li>\nLinking.addEventListener('url', ...)<\/code><\/li>\nuni_links<\/code> or app_links<\/code> package<\/li>\n<\/ul>\n\n\n\nPattern 1: Shared Route Table<\/h2>\n\n\n\n
Route Definition<\/h3>\n\n\n\n
\/\/ routes.ts (shared across all platforms)\ninterface RouteMatch {\n screen: string;\n params: Record<string, string>;\n}\n\ninterface RoutePattern {\n pattern: RegExp;\n screen: string;\n paramNames: string[];\n}\n\nconst routes: RoutePattern[] = [\n {\n pattern: \/^\\\/products\\\/([^\/]+)$\/,\n screen: 'ProductDetail',\n paramNames: ['productId']\n },\n {\n pattern: \/^\\\/offers\\\/([^\/]+)$\/,\n screen: 'OfferDetail',\n paramNames: ['offerId']\n },\n {\n pattern: \/^\\\/referral\\\/([^\/]+)$\/,\n screen: 'Referral',\n paramNames: ['referrerId']\n },\n {\n pattern: \/^\\\/categories\\\/([^\/]+)\\\/products$\/,\n screen: 'CategoryProducts',\n paramNames: ['categoryId']\n },\n {\n pattern: \/^\\\/search$\/,\n screen: 'Search',\n paramNames: []\n }\n];\n\nexport function matchRoute(urlString: string): RouteMatch | null {\n const url = new URL(urlString);\n const path = url.pathname;\n\n for (const route of routes) {\n const match = path.match(route.pattern);\n if (match) {\n const params: Record<string, string> = {};\n route.paramNames.forEach((name, i) => {\n params[name] = match[i + 1];\n });\n\n \/\/ Include query parameters\n url.searchParams.forEach((value, key) => {\n params[key] = value;\n });\n\n return { screen: route.screen, params };\n }\n }\n\n return null;\n}\n<\/code><\/pre>\n\n\n\nPlatform-Specific Entry Points<\/h3>\n\n\n\n
func application(_ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {\n guard let url = userActivity.webPageUrl else { return false }\n\n \/\/ Call shared routing logic (via JavaScript bridge, or re-implement in Swift)\n let route = DeepLinkRouter.match(url: url)\n if let route = route {\n navigate(to: route.screen, params: route.params)\n return true\n }\n return false\n}\n<\/code><\/pre>\n\n\n\noverride fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n intent?.data?.let { uri ->\n val route = DeepLinkRouter.match(uri.toString())\n route?.let { navigateTo(it.screen, it.params) }\n }\n}\n\noverride fun onNewIntent(intent: Intent) {\n super.onNewIntent(intent)\n intent.data?.let { uri ->\n val route = DeepLinkRouter.match(uri.toString())\n route?.let { navigateTo(it.screen, it.params) }\n }\n}\n<\/code><\/pre>\n\n\n\n\/\/ On page load or route change\nconst route = matchRoute(window.location.href);\nif (route) {\n renderScreen(route.screen, route.params);\n}\n<\/code><\/pre>\n\n\n\nPattern 2: URL-to-Action Mapping<\/h2>\n\n\n\n
\/\/ actions.ts\ntype DeepLinkAction =\n | { type: 'VIEW_PRODUCT'; productId: string; source?: string }\n | { type: 'VIEW_OFFER'; offerId: string }\n | { type: 'APPLY_REFERRAL'; referrerId: string }\n | { type: 'SEARCH'; query: string }\n | { type: 'OPEN_HOME' };\n\nexport function urlToAction(urlString: string): DeepLinkAction {\n const url = new URL(urlString);\n const path = url.pathname;\n const query = url.searchParams;\n\n const productMatch = path.match(\/^\\\/products\\\/([^\/]+)$\/);\n if (productMatch) {\n return {\n type: 'VIEW_PRODUCT',\n productId: productMatch[1],\n source: query.get('ref') ?? undefined\n };\n }\n\n const offerMatch = path.match(\/^\\\/offers\\\/([^\/]+)$\/);\n if (offerMatch) {\n return { type: 'VIEW_OFFER', offerId: offerMatch[1] };\n }\n\n const referralMatch = path.match(\/^\\\/referral\\\/([^\/]+)$\/);\n if (referralMatch) {\n return { type: 'APPLY_REFERRAL', referrerId: referralMatch[1] };\n }\n\n if (path === '\/search') {\n return { type: 'SEARCH', query: query.get('q') ?? '' };\n }\n\n return { type: 'OPEN_HOME' };\n}\n<\/code><\/pre>\n\n\n\n\/\/ iOS, Android, web each implement this interface\ninterface ActionHandler {\n handleAction(action: DeepLinkAction): void;\n}\n\n\/\/ Example: React Native handler\nclass RNActionHandler implements ActionHandler {\n handleAction(action: DeepLinkAction) {\n switch (action.type) {\n case 'VIEW_PRODUCT':\n navigation.navigate('ProductDetail', {\n productId: action.productId\n });\n break;\n case 'APPLY_REFERRAL':\n \/\/ Store referral, then navigate\n ReferralStore.save(action.referrerId);\n navigation.navigate('Home');\n break;\n \/\/ ...\n }\n }\n}\n<\/code><\/pre>\n\n\n\nPattern 3: Configuration-Driven Routes<\/h2>\n\n\n\n
{\n "routes": [\n {\n "path": "\/products\/:productId",\n "screen": "ProductDetail",\n "requiresAuth": false\n },\n {\n "path": "\/account\/settings",\n "screen": "AccountSettings",\n "requiresAuth": true\n },\n {\n "path": "\/offers\/:offerId",\n "screen": "OfferDetail",\n "requiresAuth": false\n },\n {\n "path": "\/checkout\/:cartId",\n "screen": "Checkout",\n "requiresAuth": true\n }\n ]\n}\n<\/code><\/pre>\n\n\n\nfunction pathToRegex(path: string): { regex: RegExp; paramNames: string[] } {\n const paramNames: string[] = [];\n const regexStr = path.replace(\/:([^\/]+)\/g, (_, name) => {\n paramNames.push(name);\n return '([^\/]+)';\n });\n return {\n regex: new RegExp(`^${regexStr}$`),\n paramNames\n };\n}\n<\/code><\/pre>\n\n\n\nHandling Platform Differences<\/h2>\n\n\n\n
Authentication Gates<\/h3>\n\n\n\n
function handleAuthenticatedRoute(\n route: RouteMatch,\n isLoggedIn: boolean,\n platform: 'ios' | 'android' | 'web'\n) {\n if (isLoggedIn) {\n navigate(route.screen, route.params);\n return;\n }\n\n \/\/ Save the intended destination\n saveDeepLinkDestination(route);\n\n \/\/ Platform-specific login flow\n if (platform === 'web') {\n \/\/ Redirect to login page with return URL\n window.location.href = `\/login?returnTo=${encodeURIComponent(route.screen)}`;\n } else {\n \/\/ Show native login screen, then navigate after success\n showLoginScreen();\n }\n}\n<\/code><\/pre>\n\n\n\nFallback Behavior<\/h3>\n\n\n\n