Deep links let a URL open a specific screen inside your app instead of just launching the home screen. A user taps a link in an email, a text message, or a web page, and your app opens directly to the right product, profile, or piece of content. No detour through the home screen. No "please navigate to…" instructions.<\/p>\n\n\n\n
This tutorial walks through the full implementation: planning your URL structure, configuring iOS Universal Links, configuring Android App Links, writing route handlers in Swift and Kotlin, and dealing with the edge cases that catch most developers off guard.<\/p>\n\n\n\n
If you want a higher-level overview of what deep links actually are and why they matter, start with our guide on how deep linking works<\/a> or the deep linking concepts guide<\/a> before continuing here.<\/p>\n\n\n\n Before touching Xcode or Android Studio, decide what your URLs will look like. This matters more than most developers expect. A URL structure is hard to change once it is in the wild, and a poorly designed one leads to fragile routing logic.<\/p>\n\n\n\n Good deep link URLs follow the same conventions as good web URLs:<\/p>\n\n\n\n A simple example schema:<\/p>\n\n\n\n Write these down before you write a single line of handler code. You will reference them throughout the implementation.<\/p>\n\n\n\n Universal Links are Apple's mechanism for opening your app from a standard HTTPS URL. When iOS sees a URL that matches your app's registered domains, it opens your app instead of Safari. If the app is not installed, it falls back to the web URL.<\/p>\n\n\n\n The AASA file is a JSON document hosted at the root of your domain. iOS fetches it when your app is installed, then uses it to decide which URL paths to intercept. For a detailed walkthrough of the AASA file format and common mistakes, see our AASA file setup guide<\/a>.<\/p>\n\n\n\n Create a file called Replace Host this file at:<\/p>\n\n\n\n Both paths work. Apple checks both. The file must be served over HTTPS with a Open your project in Xcode and go to your app target's Signing & Capabilities<\/strong> tab. Click + Capability<\/strong> and add Associated Domains<\/strong>.<\/p>\n\n\n\n Add your domain with the If you use subdomains, add each one separately:<\/p>\n\n\n\n This entitlement gets embedded in your app binary and tells iOS which domains to check for an AASA file.<\/p>\n\n\n\n iOS delivers Universal Links to your app through For a UIKit app:<\/p>\n\n\n\n For a SwiftUI app using the The Android App Links use a similar pattern: a JSON verification file hosted on your server, a manifest configuration, and a handler in your Activity.<\/p>\n\n\n\n Create a file called The file format looks like this:<\/p>\n\n\n\n To get your SHA-256 certificate fingerprint from your keystore:<\/p>\n\n\n\n For debug builds, Android Studio generates a debug keystore automatically. You can get its fingerprint with:<\/p>\n\n\n\n You can verify your setup using the Android Asset Links validator<\/a>.<\/p>\n\n\n\n In The In your Both platforms now call into a router. This is where your URL paths map to screens.<\/p>\n\n\n\n Keep the router lean. It should parse, match, and delegate. Business logic belongs in the destination screens.<\/p>\n\n\n\n The happy path is straightforward. The edge cases are where most implementations break.<\/p>\n\n\n\n When iOS or Android cannot open your app (because it is not installed), the fallback is the web URL. This means your web server needs to handle every deep link path gracefully. At minimum, serve a page with an App Store or Play Store link. Better yet, use that web page to save the deep link destination and resume navigation after install. This is called deferred deep linking, and it requires a server-side component to work correctly. Our guide on building deferred deep links<\/a> covers the implementation in detail.<\/p>\n\n\n\n Tolinku<\/a> handles deferred deep linking automatically: the install destination is stored server-side and delivered to the app on first open, so users land exactly where they intended even after a fresh install.<\/p>\n\n\n\n Not every URL your router receives will be valid. Product IDs get deleted. Invite codes expire. Order IDs belong to other users. Handle these cases explicitly rather than crashing or showing a blank screen.<\/p>\n\n\n\n In Swift:<\/p>\n\n\n\n Return the user to a sensible fallback screen rather than leaving them on a broken state. The product screen itself should handle the case where the API returns a 404.<\/p>\n\n\n\n On iOS, Universal Links delivered at cold launch arrive before your root view controller is fully set up. If you push a view controller immediately in A clean pattern is to store the pending URL and process it after the UI is ready:<\/p>\n\n\n\n Then in your root view controller's Testing deep links requires real devices or simulators, not just unit tests. For a comprehensive look at available tools and approaches, see our deep link testing tools<\/a> roundup.<\/p>\n\n\n\n From Terminal, use For a device, use the Notes app: type the URL, long-press it, and tap "Open". Safari will route it through Universal Links.<\/p>\n\n\n\n To test cold launch (app not running), terminate the app first, then use Use Add the Test with the app in the background (press home, then run the command) and with the app fully closed. Both scenarios exercise different code paths.<\/p>\n\n\n\n On Android, you can check whether domain verification succeeded:<\/p>\n\n\n\n Look for This implementation covers the fundamentals: URL structure, platform configuration files, Swift and Kotlin handlers, routing logic, and common edge cases. From here, the natural extensions are deferred deep linking (handling installs mid-flow), analytics on which links are driving conversions, and smart banners that surface your app to web visitors without being intrusive.<\/p>\n\n\n\nStep 1: Plan Your URL Structure<\/h2>\n\n\n\n
\n
\/products\/123<\/code>, not \/view-product?id=123<\/code>)<\/li>\n\/u\/:username<\/code>, products at \/products\/:id<\/code>)<\/li>\nhttps:\/\/yourapp.com\/products\/:productId\nhttps:\/\/yourapp.com\/u\/:username\nhttps:\/\/yourapp.com\/orders\/:orderId\nhttps:\/\/yourapp.com\/invite\/:code\n<\/code><\/pre>\n\n\n\nStep 2: Set Up iOS Universal Links<\/h2>\n\n\n\n
2a. Create the Apple App Site Association File<\/h3>\n\n\n\n
apple-app-site-association<\/code> (no file extension) with this structure:<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["TEAMID.com.yourcompany.yourapp"],\n "components": [\n {\n "\/": "\/products\/*",\n "comment": "Product detail pages"\n },\n {\n "\/": "\/u\/*",\n "comment": "User profiles"\n },\n {\n "\/": "\/orders\/*",\n "comment": "Order details"\n },\n {\n "\/": "\/invite\/*",\n "comment": "Invite links"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nTEAMID<\/code> with your Apple Developer Team ID<\/a>, and update the bundle identifier to match your app.<\/p>\n\n\n\nhttps:\/\/yourapp.com\/.well-known\/apple-app-site-association\nhttps:\/\/yourapp.com\/apple-app-site-association\n<\/code><\/pre>\n\n\n\nContent-Type<\/code> of application\/json<\/code>. No redirects. Apple's CDN fetches this file and caches it, so changes can take time to propagate. You can verify your file using Apple's AASA validator<\/a>.<\/p>\n\n\n\n2b. Enable Associated Domains in Xcode<\/h3>\n\n\n\n
applinks:<\/code> prefix:<\/p>\n\n\n\napplinks:yourapp.com\n<\/code><\/pre>\n\n\n\napplinks:www.yourapp.com\napplinks:yourapp.com\n<\/code><\/pre>\n\n\n\n2c. Handle Incoming URLs in Swift<\/h3>\n\n\n\n
UIApplicationDelegate<\/code> or SceneDelegate<\/code>. The entry point is application(_:continue:restorationHandler:)<\/code>.<\/p>\n\n\n\nimport UIKit\n\n@main\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n\n func application(\n _ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void\n ) -> Bool {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let url = userActivity.webpageURL else {\n return false\n }\n return DeepLinkRouter.shared.handle(url: url)\n }\n}\n<\/code><\/pre>\n\n\n\nonOpenURL<\/code> modifier:<\/p>\n\n\n\n@main\nstruct YourApp: App {\n var body: some Scene {\n WindowGroup {\n ContentView()\n .onOpenURL { url in\n DeepLinkRouter.shared.handle(url: url)\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\nDeepLinkRouter<\/code> is where your actual routing logic lives. We will build that in Step 4.<\/p>\n\n\n\nStep 3: Set Up Android App Links<\/h2>\n\n\n\n
3a. Create the Digital Asset Links File<\/h3>\n\n\n\n
assetlinks.json<\/code> (see our complete Digital Asset Links setup guide<\/a> for details) and host it at:<\/p>\n\n\n\nhttps:\/\/yourapp.com\/.well-known\/assetlinks.json\n<\/code><\/pre>\n\n\n\n[\n {\n "relation": ["delegate_permission\/common.handle_all_urls"],\n "target": {\n "namespace": "android_app",\n "package_name": "com.yourcompany.yourapp",\n "sha256_cert_fingerprints": [\n "AA:BB:CC:DD:EE:FF:..."\n ]\n }\n }\n]\n<\/code><\/pre>\n\n\n\nkeytool -list -v -keystore your-release.keystore -alias your-alias\n<\/code><\/pre>\n\n\n\nkeytool -list -v -keystore ~\/.android\/debug.keystore -alias androiddebugkey -storepass android -keypass android\n<\/code><\/pre>\n\n\n\n3b. Configure Your Android Manifest<\/h3>\n\n\n\n
AndroidManifest.xml<\/code>, add an intent filter to the Activity that should handle deep links:<\/p>\n\n\n\n<activity\n android:name=".MainActivity"\n android:exported="true"\n android:launchMode="singleTask">\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\n <data\n android:scheme="https"\n android:host="yourapp.com" \/>\n <\/intent-filter>\n\n<\/activity>\n<\/code><\/pre>\n\n\n\nandroid:autoVerify="true"<\/code> attribute is what makes these App Links rather than plain deep links. Android will verify your domain ownership through the assetlinks.json<\/code> file before granting automatic link handling. Without it, Android shows a disambiguation dialog asking the user which app to open the link in.<\/p>\n\n\n\n3c. Handle Incoming Intents in Kotlin<\/h3>\n\n\n\n
MainActivity<\/code>, handle the incoming intent in onCreate<\/code> and onNewIntent<\/code>:<\/p>\n\n\n\nimport android.content.Intent\nimport android.net.Uri\nimport android.os.Bundle\nimport androidx.appcompat.app.AppCompatActivity\n\nclass MainActivity : AppCompatActivity() {\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n setContentView(R.layout.activity_main)\n\n intent?.let { handleIntent(it) }\n }\n\n override fun onNewIntent(intent: Intent) {\n super.onNewIntent(intent)\n handleIntent(intent)\n }\n\n private fun handleIntent(intent: Intent) {\n if (intent.action == Intent.ACTION_VIEW) {\n intent.data?.let { uri ->\n DeepLinkRouter.handle(uri, this)\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\nonNewIntent<\/code> fires when the Activity is already running and a new intent arrives (because of singleTask<\/code> launch mode). You need both handlers or you will miss links that arrive while the app is open.<\/p>\n\n\n\nStep 4: Build a Simple Router<\/h2>\n\n\n\n
Swift Router<\/h3>\n\n\n\n
import UIKit\n\nfinal class DeepLinkRouter {\n\n static let shared = DeepLinkRouter()\n private init() {}\n\n @discardableResult\n func handle(url: URL) -> Bool {\n guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {\n return false\n }\n\n let pathComponents = components.path\n .split(separator: "\/")\n .map(String.init)\n\n switch pathComponents.first {\n case "products":\n if let productId = pathComponents.dropFirst().first {\n navigateToProduct(id: productId)\n return true\n }\n case "u":\n if let username = pathComponents.dropFirst().first {\n navigateToProfile(username: username)\n return true\n }\n case "invite":\n if let code = pathComponents.dropFirst().first {\n navigateToInvite(code: code)\n return true\n }\n default:\n break\n }\n\n return false\n }\n\n private func navigateToProduct(id: String) {\n \/\/ Push ProductViewController onto the navigation stack\n }\n\n private func navigateToProfile(username: String) {\n \/\/ Push ProfileViewController onto the navigation stack\n }\n\n private func navigateToInvite(code: String) {\n \/\/ Present InviteViewController\n }\n}\n<\/code><\/pre>\n\n\n\nKotlin Router<\/h3>\n\n\n\n
import android.content.Context\nimport android.net.Uri\n\nobject DeepLinkRouter {\n\n fun handle(uri: Uri, context: Context): Boolean {\n val segments = uri.pathSegments\n\n if (segments.isEmpty()) return false\n\n return when (segments[0]) {\n "products" -> {\n val productId = segments.getOrNull(1) ?: return false\n navigateToProduct(productId, context)\n true\n }\n "u" -> {\n val username = segments.getOrNull(1) ?: return false\n navigateToProfile(username, context)\n true\n }\n "invite" -> {\n val code = segments.getOrNull(1) ?: return false\n navigateToInvite(code, context)\n true\n }\n else -> false\n }\n }\n\n private fun navigateToProduct(id: String, context: Context) {\n \/\/ Start ProductActivity with productId as an extra\n }\n\n private fun navigateToProfile(username: String, context: Context) {\n \/\/ Start ProfileActivity with username as an extra\n }\n\n private fun navigateToInvite(code: String, context: Context) {\n \/\/ Start InviteActivity with code as an extra\n }\n}\n<\/code><\/pre>\n\n\n\nStep 5: Handle Edge Cases<\/h2>\n\n\n\n
App Not Installed<\/h3>\n\n\n\n
Invalid or Expired Paths<\/h3>\n\n\n\n
private func navigateToProduct(id: String) {\n guard !id.isEmpty else {\n navigateToHome()\n return\n }\n \/\/ Proceed with navigation, handle 404 in the product screen itself\n}\n<\/code><\/pre>\n\n\n\nState Restoration Timing<\/h3>\n\n\n\n
application(_:continue:restorationHandler:)<\/code>, you may push onto nothing.<\/p>\n\n\n\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n var pendingDeepLink: URL?\n\n func application(\n _ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void\n ) -> Bool {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let url = userActivity.webpageURL else { return false }\n pendingDeepLink = url\n return true\n }\n}\n<\/code><\/pre>\n\n\n\nviewDidAppear<\/code>:<\/p>\n\n\n\noverride func viewDidAppear(_ animated: Bool) {\n super.viewDidAppear(animated)\n if let url = (UIApplication.shared.delegate as? AppDelegate)?.pendingDeepLink {\n DeepLinkRouter.shared.handle(url: url)\n (UIApplication.shared.delegate as? AppDelegate)?.pendingDeepLink = nil\n }\n}\n<\/code><\/pre>\n\n\n\nStep 6: Test on Both Platforms<\/h2>\n\n\n\n
Testing on iOS<\/h3>\n\n\n\n
xcrun simctl<\/code> to simulate a Universal Link opening in the simulator:<\/p>\n\n\n\nxcrun simctl openurl booted "https:\/\/yourapp.com\/products\/abc123"\n<\/code><\/pre>\n\n\n\nopenurl<\/code>. Watch the console output in Xcode for any routing errors.<\/p>\n\n\n\nTesting on Android<\/h3>\n\n\n\n
adb<\/code> to send an intent to your app:<\/p>\n\n\n\nadb shell am start \\\n -W -a android.intent.action.VIEW \\\n -d "https:\/\/yourapp.com\/products\/abc123" \\\n com.yourcompany.yourapp\n<\/code><\/pre>\n\n\n\n-n<\/code> flag to target a specific activity if needed:<\/p>\n\n\n\nadb shell am start \\\n -W -a android.intent.action.VIEW \\\n -d "https:\/\/yourapp.com\/products\/abc123" \\\n -n com.yourcompany.yourapp\/.MainActivity\n<\/code><\/pre>\n\n\n\nVerifying App Links Verification<\/h3>\n\n\n\n
adb shell pm get-app-links com.yourcompany.yourapp\n<\/code><\/pre>\n\n\n\nverified<\/code> in the output. If it shows none<\/code> or ask<\/code>, check that your assetlinks.json<\/code> is reachable and correctly formatted.<\/p>\n\n\n\nWhere to Go Next<\/h2>\n\n\n\n