How to Implement Deep Linking in Android & iOS (Step-by-Step)
implementationandroidiosdeep linking

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.

Deeplink TeamJanuary 22, 20257 min read

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

  1. Open your project in Xcode.
  2. Select your target → Signing & Capabilities.
  3. Add Associated Domains capability.
  4. 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

StepAndroidiOS
Verification fileassetlinks.json at /.well-known/AASA at /.well-known/
App configurationintent-filter with autoVerifyAssociated Domains capability
Code to handleIntent data in ActivityNSUserActivity in Scene/AppDelegate
Deferred deep linkingNot native — requires SDKNot 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?+
Both use standard HTTPS URLs that open native app content, but they are implemented differently. Android App Links use a Digital Asset Links JSON file at /.well-known/assetlinks.json. iOS Universal Links use an Apple App Site Association (AASA) file at /.well-known/apple-app-site-association.
Do I need a custom domain for deep linking?+
Yes. Both Android App Links and iOS Universal Links require a verified HTTPS domain where you host the .well-known verification files. You can use your own domain or a subdomain provided by a deep linking platform.
What is the assetlinks.json file?+
assetlinks.json is a JSON file hosted at https://yourdomain.com/.well-known/assetlinks.json. It declares the association between your domain and your Android app by listing your app's package name and SHA-256 certificate fingerprint.
What is the Apple App Site Association file?+
The AASA file is a JSON file hosted at https://yourdomain.com/.well-known/apple-app-site-association. It tells iOS which URL paths should open your app and links your Team ID and Bundle ID to the domain.
Can I test deep links without publishing to the app store?+
Yes. You can test Android App Links with adb commands and test iOS Universal Links via TestFlight or development builds, as long as the AASA file is correctly hosted and your bundle ID matches.

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.