Kotlin Multiplatform (KMP) lets you share business logic between iOS and Android while keeping platform-specific UI and APIs. Deep link handling fits this model well: URL parsing and route matching are pure logic (shared), while receiving URLs and performing navigation are platform-specific. This article walks through building a shared deep link router in KMP.<\/p>\n\n\n\n
For Android-specific deep link patterns, see Kotlin deep link handling: modern Android patterns<\/a>. For the cross-platform overview, see cross-platform deep linking guide for 2026<\/a>.<\/p>\n\n\n\n KMP projects use KMP does not have For production use, consider the Ktor client URL utilities<\/a> which handle edge cases like percent-encoding.<\/p>\n\n\n\n Define typed actions so platform code does not need to interpret raw strings:<\/p>\n\n\n\n For the iOS side of a KMP project, you have two options: write the handler in Kotlin ( Call from Swift:<\/p>\n\n\n\n If you prefer keeping the iOS navigation code entirely in Swift, just call the router:<\/p>\n\n\n\n Add The shared module can be tested with standard Kotlin tests:<\/p>\n\n\n\n These tests run on all KMP targets (JVM, Native, JS), verifying the routing logic works identically everywhere.<\/p>\n\n\n\n Add the shared module dependency to both platform targets:<\/p>\n\n\n\n For production URL parsing, you can add Ktor:<\/p>\n\n\n\n Tolinku<\/a> hosts AASA and assetlinks.json verification files and provides deferred deep linking<\/a> for users who install the app after tapping a link. Configure your iOS and Android app details in the Appspace settings<\/a>, and Tolinku generates the verification files automatically. Routes<\/a> with dynamic parameters<\/a> work with any client-side routing implementation, including KMP shared routers.<\/p>\n\n\n\n For Android Kotlin patterns, see Kotlin deep link handling: modern Android patterns<\/a>. For Xamarin\/.NET MAUI, see Xamarin deep linking: cross-platform setup<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Implement deep linking in Kotlin Multiplatform projects. Share link parsing logic across iOS and Android with platform-specific handlers.<\/p>\n","protected":false},"author":2,"featured_media":1887,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Deep Linking with Kotlin Multiplatform (KMP)","rank_math_description":"Implement deep linking in Kotlin Multiplatform projects. Share link parsing logic across iOS and Android with platform-specific handlers.","rank_math_focus_keyword":"Kotlin Multiplatform deep links","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-kotlin-multiplatform-deep-links.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-kotlin-multiplatform-deep-links.png","footnotes":""},"categories":[15],"tags":[25,23,156,20,24,573,34,572,69,22],"class_list":["post-1888","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-engineering","tag-android","tag-app-links","tag-cross-platform","tag-deep-linking","tag-ios","tag-kmp","tag-kotlin","tag-kotlin-multiplatform","tag-mobile-development","tag-universal-links"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1888","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=1888"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1888\/revisions"}],"predecessor-version":[{"id":1889,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1888\/revisions\/1889"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/1887"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=1888"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=1888"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=1888"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Architecture<\/h2>\n\n\n\n
expect<\/code>\/actual<\/code> declarations for platform-specific code. For deep linking:<\/p>\n\n\n\n\n
commonMain<\/code>)<\/strong>: URL parsing, route matching, parameter extraction<\/li>\nandroidMain<\/code>)<\/strong>: Intent handling, Activity navigation<\/li>\niosMain<\/code>)<\/strong>: Universal Link handling, UIKit\/SwiftUI navigation<\/li>\n<\/ul>\n\n\n\ncommonMain\/\n DeepLinkRouter.kt \/\/ Route matching logic\n DeepLinkAction.kt \/\/ Action types\n UrlParser.kt \/\/ URL parsing utilities\n\nandroidMain\/\n AndroidDeepLinkHandler.kt \/\/ Intent \u2192 action\n AndroidNavigator.kt \/\/ Activity\/Fragment navigation\n\niosMain\/\n IosDeepLinkHandler.kt \/\/ NSUserActivity \u2192 action\n IosNavigator.kt \/\/ UIKit navigation\n<\/code><\/pre>\n\n\n\nShared Module: Route Matching<\/h2>\n\n\n\n
Route Definition<\/h3>\n\n\n\n
\/\/ commonMain\/DeepLinkRouter.kt\n\ndata class RouteMatch(\n val screen: String,\n val params: Map<String, String>\n)\n\ndata class RoutePattern(\n val regex: Regex,\n val screen: String,\n val paramNames: List<String>\n)\n\nobject DeepLinkRouter {\n private val routes: List<RoutePattern> = listOf(\n routePattern("\/products\/{productId}", "ProductDetail"),\n routePattern("\/offers\/{offerId}", "OfferDetail"),\n routePattern("\/referral\/{referrerId}", "Referral"),\n routePattern("\/categories\/{categoryId}\/products", "CategoryProducts"),\n routePattern("\/search", "Search")\n )\n\n fun match(urlString: String): RouteMatch? {\n val parsed = parseUrl(urlString) ?: return null\n val path = parsed.path\n\n for (route in routes) {\n val matchResult = route.regex.matchEntire(path) ?: continue\n val params = mutableMapOf<String, String>()\n\n route.paramNames.forEachIndexed { index, name ->\n params[name] = matchResult.groupValues[index + 1]\n }\n\n \/\/ Add query parameters\n parsed.queryParams.forEach { (key, value) ->\n params[key] = value\n }\n\n return RouteMatch(screen = route.screen, params = params)\n }\n\n return null\n }\n\n private fun routePattern(pattern: String, screen: String): RoutePattern {\n val paramNames = mutableListOf<String>()\n val regexStr = pattern.replace(Regex("\\\\{([^}]+)\\\\}")) { matchResult ->\n paramNames.add(matchResult.groupValues[1])\n "([^\/]+)"\n }\n return RoutePattern(\n regex = Regex("^$regexStr$"),\n screen = screen,\n paramNames = paramNames\n )\n }\n}\n<\/code><\/pre>\n\n\n\nURL Parser<\/h3>\n\n\n\n
java.net.URL<\/code> in common code. Write a simple parser or use a multiplatform library like Ktor's Url<\/code><\/a>:<\/p>\n\n\n\n\/\/ commonMain\/UrlParser.kt\n\ndata class ParsedUrl(\n val scheme: String,\n val host: String,\n val path: String,\n val queryParams: Map<String, String>\n)\n\nfun parseUrl(urlString: String): ParsedUrl? {\n \/\/ Basic URL parsing for deep link purposes\n val schemeEnd = urlString.indexOf(":\/\/")\n if (schemeEnd == -1) return null\n\n val scheme = urlString.substring(0, schemeEnd)\n val rest = urlString.substring(schemeEnd + 3)\n\n val pathStart = rest.indexOf('\/')\n if (pathStart == -1) return ParsedUrl(scheme, rest, "\/", emptyMap())\n\n val host = rest.substring(0, pathStart)\n val pathAndQuery = rest.substring(pathStart)\n\n val queryStart = pathAndQuery.indexOf('?')\n val path: String\n val queryParams: Map<String, String>\n\n if (queryStart == -1) {\n path = pathAndQuery.trimEnd('\/')\n queryParams = emptyMap()\n } else {\n path = pathAndQuery.substring(0, queryStart).trimEnd('\/')\n queryParams = parseQueryString(pathAndQuery.substring(queryStart + 1))\n }\n\n return ParsedUrl(scheme, host, path.ifEmpty { "\/" }, queryParams)\n}\n\nprivate fun parseQueryString(query: String): Map<String, String> {\n return query.split("&")\n .filter { it.contains("=") }\n .associate { param ->\n val (key, value) = param.split("=", limit = 2)\n key to value\n }\n}\n<\/code><\/pre>\n\n\n\nShared Module: Action Types<\/h2>\n\n\n\n
\/\/ commonMain\/DeepLinkAction.kt\n\nsealed class DeepLinkAction {\n data class ViewProduct(\n val productId: String,\n val source: String? = null\n ) : DeepLinkAction()\n\n data class ViewOffer(val offerId: String) : DeepLinkAction()\n\n data class ApplyReferral(val referrerId: String) : DeepLinkAction()\n\n data class Search(val query: String) : DeepLinkAction()\n\n object OpenHome : DeepLinkAction()\n}\n\nfun RouteMatch.toAction(): DeepLinkAction {\n return when (screen) {\n "ProductDetail" -> DeepLinkAction.ViewProduct(\n productId = params["productId"] ?: "",\n source = params["ref"]\n )\n "OfferDetail" -> DeepLinkAction.ViewOffer(\n offerId = params["offerId"] ?: ""\n )\n "Referral" -> DeepLinkAction.ApplyReferral(\n referrerId = params["referrerId"] ?: ""\n )\n "Search" -> DeepLinkAction.Search(\n query = params["q"] ?: ""\n )\n else -> DeepLinkAction.OpenHome\n }\n}\n<\/code><\/pre>\n\n\n\nAndroid Implementation<\/h2>\n\n\n\n
Intent Handling<\/h3>\n\n\n\n
\/\/ androidMain\/AndroidDeepLinkHandler.kt\n\nclass AndroidDeepLinkHandler(\n private val navigator: AndroidNavigator\n) {\n fun handleIntent(intent: Intent) {\n val uri = intent.data ?: return\n handleUrl(uri.toString())\n }\n\n fun handleUrl(urlString: String) {\n val route = DeepLinkRouter.match(urlString)\n val action = route?.toAction() ?: DeepLinkAction.OpenHome\n navigator.execute(action)\n }\n}\n<\/code><\/pre>\n\n\n\nActivity Setup<\/h3>\n\n\n\n
\/\/ Android Activity\nclass MainActivity : ComponentActivity() {\n private val deepLinkHandler by lazy {\n AndroidDeepLinkHandler(AndroidNavigator(this))\n }\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n \/\/ Handle deep link from launch\n deepLinkHandler.handleIntent(intent)\n }\n\n override fun onNewIntent(intent: Intent) {\n super.onNewIntent(intent)\n \/\/ Handle deep link when app is already running\n deepLinkHandler.handleIntent(intent)\n }\n}\n<\/code><\/pre>\n\n\n\nAndroid Navigation<\/h3>\n\n\n\n
\/\/ androidMain\/AndroidNavigator.kt\n\nclass AndroidNavigator(private val activity: ComponentActivity) {\n fun execute(action: DeepLinkAction) {\n when (action) {\n is DeepLinkAction.ViewProduct -> {\n \/\/ Using Jetpack Navigation or direct Intent\n val intent = Intent(activity, ProductActivity::class.java).apply {\n putExtra("productId", action.productId)\n action.source?.let { putExtra("source", it) }\n }\n activity.startActivity(intent)\n }\n is DeepLinkAction.ViewOffer -> {\n val intent = Intent(activity, OfferActivity::class.java).apply {\n putExtra("offerId", action.offerId)\n }\n activity.startActivity(intent)\n }\n is DeepLinkAction.ApplyReferral -> {\n \/\/ Store referral code, then navigate\n ReferralStore.save(action.referrerId)\n val intent = Intent(activity, HomeActivity::class.java)\n activity.startActivity(intent)\n }\n is DeepLinkAction.Search -> {\n val intent = Intent(activity, SearchActivity::class.java).apply {\n putExtra("query", action.query)\n }\n activity.startActivity(intent)\n }\n is DeepLinkAction.OpenHome -> {\n val intent = Intent(activity, HomeActivity::class.java)\n activity.startActivity(intent)\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\nAndroidManifest.xml<\/h3>\n\n\n\n
<activity\n android:name=".MainActivity"\n android:exported="true">\n\n <intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/products" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/offers" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/referral" \/>\n <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\niOS Implementation<\/h2>\n\n\n\n
iosMain<\/code>) and call it from Swift, or write it in Swift and call the shared Kotlin router.<\/p>\n\n\n\nOption 1: Kotlin
iosMain<\/code> with Swift Caller<\/h3>\n\n\n\n\/\/ iosMain\/IosDeepLinkHandler.kt\n\nclass IosDeepLinkHandler {\n fun handleUrl(urlString: String): DeepLinkAction {\n val route = DeepLinkRouter.match(urlString)\n return route?.toAction() ?: DeepLinkAction.OpenHome\n }\n}\n<\/code><\/pre>\n\n\n\n\/\/ AppDelegate.swift\nimport shared \/\/ KMP shared framework\n\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n let deepLinkHandler = IosDeepLinkHandler()\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 let action = deepLinkHandler.handleUrl(urlString: url.absoluteString)\n navigate(action: action)\n return true\n }\n\n private func navigate(action: DeepLinkAction) {\n switch action {\n case let product as DeepLinkAction.ViewProduct:\n \/\/ Navigate to product screen\n let vc = ProductViewController(productId: product.productId)\n rootNavigationController?.pushViewController(vc, animated: true)\n\n case let offer as DeepLinkAction.ViewOffer:\n let vc = OfferViewController(offerId: offer.offerId)\n rootNavigationController?.pushViewController(vc, animated: true)\n\n case let referral as DeepLinkAction.ApplyReferral:\n ReferralStore.shared.save(referrerId: referral.referrerId)\n \/\/ Navigate to home\n\n default:\n \/\/ Navigate to home\n break\n }\n }\n}\n<\/code><\/pre>\n\n\n\nOption 2: Swift-Only with Shared Router<\/h3>\n\n\n\n
import shared\n\nfunc handleDeepLink(_ url: URL) {\n guard let route = DeepLinkRouter.shared.match(urlString: url.absoluteString) else {\n navigateToHome()\n return\n }\n\n let action = DeepLinkActionKt.toAction(route)\n \/\/ Handle action in Swift...\n}\n<\/code><\/pre>\n\n\n\niOS Entitlements<\/h3>\n\n\n\n
applinks:yourdomain.com<\/code> to Associated Domains in Xcode, same as any iOS Universal Links setup.<\/p>\n\n\n\nTesting the Shared Router<\/h2>\n\n\n\n
\/\/ commonTest\/DeepLinkRouterTest.kt\n\nclass DeepLinkRouterTest {\n @Test\n fun matchesProductUrl() {\n val result = DeepLinkRouter.match(\n "https:\/\/yourdomain.com\/products\/abc123"\n )\n assertNotNull(result)\n assertEquals("ProductDetail", result.screen)\n assertEquals("abc123", result.params["productId"])\n }\n\n @Test\n fun includesQueryParameters() {\n val result = DeepLinkRouter.match(\n "https:\/\/yourdomain.com\/products\/abc123?ref=email&campaign=summer"\n )\n assertNotNull(result)\n assertEquals("email", result.params["ref"])\n assertEquals("summer", result.params["campaign"])\n }\n\n @Test\n fun returnsNullForUnknownPath() {\n val result = DeepLinkRouter.match(\n "https:\/\/yourdomain.com\/unknown\/path"\n )\n assertNull(result)\n }\n\n @Test\n fun convertToViewProductAction() {\n val route = DeepLinkRouter.match(\n "https:\/\/yourdomain.com\/products\/abc123?ref=email"\n )!!\n val action = route.toAction()\n assertTrue(action is DeepLinkAction.ViewProduct)\n assertEquals("abc123", (action as DeepLinkAction.ViewProduct).productId)\n assertEquals("email", action.source)\n }\n\n @Test\n fun handlesTrailingSlash() {\n val result = DeepLinkRouter.match(\n "https:\/\/yourdomain.com\/products\/abc123\/"\n )\n assertNotNull(result)\n assertEquals("abc123", result.params["productId"])\n }\n}\n<\/code><\/pre>\n\n\n\nGradle Configuration<\/h2>\n\n\n\n
\/\/ shared\/build.gradle.kts\nkotlin {\n androidTarget()\n iosX64()\n iosArm64()\n iosSimulatorArm64()\n\n sourceSets {\n commonMain.dependencies {\n \/\/ No external dependencies needed for basic routing\n }\n commonTest.dependencies {\n implementation(kotlin("test"))\n }\n }\n}\n<\/code><\/pre>\n\n\n\ncommonMain.dependencies {\n implementation("io.ktor:ktor-http:3.1.0")\n}\n<\/code><\/pre>\n\n\n\nTolinku for KMP Projects<\/h2>\n\n\n\n