How to Implement Deep Linking in Android & iOS (Step-by-Step)
Android and iOS handle deep links differently. Learn the implementation steps, common challenges, and how a unified platform simplifies cross-platform support.
Deep linking on mobile requires platform-specific configuration. Android and iOS each have their own verification mechanism, and getting the details wrong means links silently fail—opening a browser instead of your app, or not opening at all. This guide walks through the exact steps for both platforms.
Prerequisites
Before you start:
- A registered Android app (package name) and/or iOS app (Bundle ID + Team ID).
- A verified HTTPS domain where you can host files at the
.well-known/path. - Access to your app's signing keys.
Part 1: Android App Links
Step 1 – Create the Digital Asset Links file
Create a file at https://yourdomain.com/.well-known/assetlinks.json:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.yourcompany.yourapp",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:..."
]
}
}]
Get your SHA-256 fingerprint with:
keytool -list -v -keystore your-release-key.jks -alias your-alias
The file must be served with Content-Type: application/json and no redirects on the path.
Step 2 – Configure intent filters in AndroidManifest.xml
<activity android:name=".MainActivity">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="yourdomain.com"
android:pathPrefix="/app" />
</intent-filter>
</activity>
The android:autoVerify="true" attribute triggers automatic domain verification on install.
Step 3 – Handle the incoming intent
In your MainActivity:
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val action = intent.action
val data = intent.data
if (Intent.ACTION_VIEW == action && data != null) {
handleDeepLink(data)
}
}
private fun handleDeepLink(uri: Uri) {
val path = uri.path ?: return
// Route to the correct screen based on path
}
Step 4 – Verify
Use the Android Digital Asset Links verification tool:
https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls
Expect complete: true in the response.
Part 2: iOS Universal Links
Step 1 – Create the Apple App Site Association file
Create https://yourdomain.com/.well-known/apple-app-site-association (no file extension):
{
"applinks": {
"apps": [],
"details": [
{
"appID": "TEAMID.com.yourcompany.yourapp",
"paths": ["/app/*", "/share/*"]
}
]
}
}
TEAMID is your 10-character Apple Developer Team ID. The file must be served over HTTPS with no redirect.
Step 2 – Enable Associated Domains in Xcode
- Open your project in Xcode.
- Select your target → Signing & Capabilities.
- Add Associated Domains capability.
- Add entry:
applinks:yourdomain.com
Step 3 – Handle the URL in AppDelegate or SceneDelegate
// SceneDelegate.swift
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let url = userActivity.webpageURL else { return }
handleDeepLink(url)
}
func handleDeepLink(_ url: URL) {
let path = url.path
// Route to the correct screen
}
Step 4 – Test
Use a TestFlight or development build. Open the link in Notes or Safari and tap it—it should open the app directly.
Common iOS pitfall: The AASA file is fetched by Apple's CDN at app install time, not at runtime. If you update the file, users need to reinstall or the OS needs to refresh it (which can take time). Always validate your AASA with the AASA Validator before submitting.
Part 3: Handling Edge Cases
App not installed fallback
Configure a fallback URL for when the app is not installed. This can be:
- An App Store / Play Store redirect.
- A marketing landing page with smart app banner.
- A web version of the content.
Deferred deep linking
Neither Android App Links nor Universal Links natively support preserving context across an install. You need a server-side platform for this. When a user clicks your link and is redirected to the store, the platform stores their click data. Your SDK retrieves it on first launch and routes accordingly.
Link in a WebView
Deep links clicked inside a WebView may not trigger the OS intent-handling mechanism. Configure your WebViewClient (Android) or WKNavigationDelegate (iOS) to intercept deep link URLs and route them appropriately.
Using a Platform Instead of Building From Scratch
Building and maintaining AASA files, Digital Asset Links, deferred routing, and analytics across both platforms is a significant ongoing engineering investment. Platforms like Deeplink provide:
- Managed hosting of AASA and assetlinks.json files.
- Deferred deep linking with server-side click storage.
- Dashboard for creating and managing links without code.
- Analytics per link and per campaign.
- REST API for programmatic link creation.
If your team's focus is product rather than infrastructure, using a dedicated platform is typically faster and more reliable than building the stack yourself.
Summary
| Step | Android | iOS |
|---|---|---|
| Verification file | assetlinks.json at /.well-known/ | AASA at /.well-known/ |
| App configuration | intent-filter with autoVerify | Associated Domains capability |
| Code to handle | Intent data in Activity | NSUserActivity in Scene/AppDelegate |
| Deferred deep linking | Not native — requires SDK | Not native — requires SDK |
Getting these steps right takes a day or two of careful implementation. The reward is links that open the right screen in your app every time—no browser flash, no home-screen confusion.
Frequently Asked Questions
What is the difference between Android App Links and iOS Universal Links?+
Do I need a custom domain for deep linking?+
What is the assetlinks.json file?+
What is the Apple App Site Association file?+
Can I test deep links without publishing to the app store?+
Ready to implement deep linking?
Deeplink gives you deferred deep linking, Android App Links, and iOS Universal Links — with a dashboard, REST API, and analytics.

