{"id":367,"date":"2026-03-05T17:00:00","date_gmt":"2026-03-05T22:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=367"},"modified":"2026-03-07T04:33:12","modified_gmt":"2026-03-07T09:33:12","slug":"android-app-links-complete-guide","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/android-app-links-complete-guide\/","title":{"rendered":"Android App Links: Complete Implementation Guide"},"content":{"rendered":"\n

Android App Links let your app open directly when a user taps a URL that belongs to your domain. No disambiguation dialog. No browser redirect. The user taps a link, and your app handles it immediately.<\/p>\n\n\n\n

This is different from regular deep links or custom URI schemes. Android App Links are verified: Google confirms that you own the domain and that the domain explicitly trusts your app. Once verification passes, Android routes matching URLs straight to your app without asking the user to choose between your app and a browser.<\/p>\n\n\n\n

This guide covers every step of the implementation process, from hosting the Digital Asset Links file to handling incoming links in Kotlin, testing with adb<\/code>, and debugging common verification failures. For iOS, see the equivalent guide: Universal Links: everything you need to know<\/a>.<\/p>\n\n\n\n

How Android App Links Differ from Regular Deep Links<\/h2>\n\n\n\n

Android supports three types of links that can open apps:<\/p>\n\n\n\n

    \n

  1. Custom URI schemes<\/strong> (e.g., myapp:\/\/product\/123<\/code>). These are not web URLs. They work only if the app is installed, and any app can claim the same scheme. There is no ownership verification.<\/p>\n\n\n\n

    Standard deep links<\/strong> (regular http<\/code>\/https<\/code> intent filters without autoVerify<\/code>). These trigger the disambiguation dialog, where Android asks the user which app or browser should handle the URL.<\/p>\n\n\n\n

    Android App Links<\/strong> (http<\/code>\/https<\/code> intent filters with autoVerify="true"<\/code>). These skip the disambiguation dialog entirely because Android has verified that the domain owner authorized the app.<\/p>\n\n\n\n

    The key difference is trust. With App Links, you prove domain ownership through a Digital Asset Links<\/a> file hosted on your server. Android downloads this file during app installation (or update) and checks it against your app's signing certificate. If everything matches, your app becomes the default handler for those URLs.<\/p>\n\n\n\n

    For a broader overview of how App Links fit into the deep linking landscape, see the Tolinku App Links concepts documentation<\/a>.<\/p>\n\n\n\n

    The Verification Flow<\/h2>\n\n\n\n

    Here is what happens under the hood when a user installs your app:<\/p>\n\n\n\n

      \n
    1. Android reads your app's manifest and finds intent filters with android:autoVerify="true"<\/code>.<\/li>\n
    2. For each declared domain, Android sends a request to https:\/\/{domain}\/.well-known\/assetlinks.json<\/code>.<\/li>\n
    3. Android parses the JSON response and checks whether your app's package name and SHA-256 certificate fingerprint are listed.<\/li>\n
    4. If the file is valid and the fingerprint matches, Android marks your app as the verified handler for that domain.<\/li>\n
    5. From that point forward, any URL matching your intent filter pattern opens your app directly.<\/li>\n<\/ol>\n\n\n\n

      If verification fails for any domain in your intent filter, Android falls back to the disambiguation dialog for URLs on that domain. Verification must succeed for every domain you declare; a single failure does not block other domains from verifying.<\/p>\n\n\n\n

      On Android 12 (API 31) and later, the verification process changed. For details on Android 12+ changes, see Android 12 App Links changes<\/a>. The system now uses a domain verification API<\/a> that re-verifies links periodically rather than only at install time. This means fixing a broken assetlinks.json<\/code> file can resolve verification without requiring users to reinstall your app.<\/p>\n\n\n\n

      The Digital Asset Links File<\/h2>\n\n\n\n

      The Digital Asset Links file is the cornerstone of App Links verification. It is a JSON file hosted at a specific path on your domain.<\/p>\n\n\n\n

      File Location<\/h3>\n\n\n\n

      The file must be accessible at:<\/p>\n\n\n\n

      https:\/\/yourdomain.com\/.well-known\/assetlinks.json\n<\/code><\/pre>\n\n\n\n
      For a step-by-step setup walkthrough, see the Digital Asset Links setup guide<\/a>. No redirects. No HTTP (it must be HTTPS). The response must have a Content-Type<\/code> of application\/json<\/code>. The URL must return a 200<\/code> status code.<\/p>\n\n\n\n
      File Format<\/h3>\n\n\n\n
      [\n  {\n    "relation": ["delegate_permission\/common.handle_all_urls"],\n    "target": {\n      "namespace": "android_app",\n      "package_name": "com.example.myapp",\n      "sha256_cert_fingerprints": [\n        "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90"\n      ]\n    }\n  }\n]\n<\/code><\/pre>\n\n\n\n
      The file is a JSON array. Each object declares a relationship between your domain and an Android app. You can list multiple apps (for example, a production build and a debug build) by adding more objects to the array.<\/p>\n\n\n\n
      Getting Your SHA-256 Fingerprint<\/h3>\n\n\n\n
      For your debug keystore:<\/p>\n\n\n\n
      keytool -list -v -keystore ~\/.android\/debug.keystore -alias androiddebugkey -storepass android -keypass android\n<\/code><\/pre>\n\n\n\n
      For your release keystore:<\/p>\n\n\n\n
      keytool -list -v -keystore \/path\/to\/your-release-key.keystore -alias your-alias\n<\/code><\/pre>\n\n\n\n
      If you use Google Play App Signing<\/a>, you need the fingerprint from the Play Console, not from your local upload key. Go to Play Console > Your App > Setup > App signing<\/strong> and copy the SHA-256 fingerprint from the "App signing key certificate" section.<\/p>\n\n\n\n
      This is a common mistake. If you use Play App Signing (which is now required for new apps), your local keystore fingerprint will not match what Android uses for verification on production devices. You need both fingerprints in your assetlinks.json<\/code>: the Play signing key for production and your upload key for local testing.<\/p>\n\n\n\n
      [\n  {\n    "relation": ["delegate_permission\/common.handle_all_urls"],\n    "target": {\n      "namespace": "android_app",\n      "package_name": "com.example.myapp",\n      "sha256_cert_fingerprints": [\n        "AA:BB:CC:...:PLAY_SIGNING_KEY_FINGERPRINT",\n        "DD:EE:FF:...:UPLOAD_KEY_FINGERPRINT"\n      ]\n    }\n  }\n]\n<\/code><\/pre>\n\n\n\n
      Setting Up Intent Filters<\/h2>\n\n\n\n
      Your app declares which URLs it handles through intent filters in AndroidManifest.xml<\/code>.<\/p>\n\n\n\n
      Basic Intent Filter<\/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\n            android:scheme="https"\n            android:host="yourdomain.com"\n            android:pathPrefix="\/product" \/>\n    <\/intent-filter>\n\n<\/activity>\n<\/code><\/pre>\n\n\n\n
      The critical attribute is android:autoVerify="true"<\/code>. Without it, Android treats the intent filter as a regular deep link and shows the disambiguation dialog.<\/p>\n\n\n\n
      Path Matching Options<\/h3>\n\n\n\n
      Android supports three path matching attributes:<\/p>\n\n\n\n
      \n\n\n\n\n\n
      Attribute<\/th>\nExample<\/th>\nMatches<\/th>\n<\/tr>\n<\/thead>\n
      android:path<\/code><\/td>\n\/product\/featured<\/code><\/td>\nExact path only<\/td>\n<\/tr>\n
      android:pathPrefix<\/code><\/td>\n\/product<\/code><\/td>\n\/product<\/code>, \/product\/123<\/code>, \/product\/abc\/details<\/code><\/td>\n<\/tr>\n
      android:pathPattern<\/code><\/td>\n\/product\/.*\/details<\/code><\/td>\nPaths matching the pattern (uses .*<\/code> for wildcards)<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
      For most deep linking setups, pathPrefix<\/code> provides the right balance between specificity and flexibility.<\/p>\n\n\n\n
      Multiple Domains<\/h3>\n\n\n\n
      If your app handles links from multiple domains, add separate <data><\/code> elements or separate intent filters:<\/p>\n\n\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    <data android:host="yourdomain.com" \/>\n    <data android:host="www.yourdomain.com" \/>\n    <data android:pathPrefix="\/product" \/>\n<\/intent-filter>\n<\/code><\/pre>\n\n\n\n
      Remember: each domain listed here must have its own valid assetlinks.json<\/code> file. If www.yourdomain.com<\/code> does not serve the file correctly, verification fails for that domain (though yourdomain.com<\/code> can still verify independently on Android 12+).<\/p>\n\n\n\n
      For more details on configuring your Android app with Tolinku, see the Android configuration guide<\/a>.<\/p>\n\n\n\n
      Handling Deep Links in Your Activity<\/h2>\n\n\n\n
      Once Android opens your activity through an App Link, you need to read the incoming URL and navigate the user to the right screen.<\/p>\n\n\n\n
      Basic Kotlin Handling<\/h3>\n\n\n\n
      class MainActivity : ComponentActivity() {\n\n    override fun onCreate(savedInstanceState: Bundle?) {\n        super.onCreate(savedInstanceState)\n        handleDeepLink(intent)\n    }\n\n    override fun onNewIntent(intent: Intent) {\n        super.onNewIntent(intent)\n        handleDeepLink(intent)\n    }\n\n    private fun handleDeepLink(intent: Intent) {\n        if (intent.action != Intent.ACTION_VIEW) return\n\n        val uri = intent.data ?: return\n        val path = uri.path ?: return\n\n        when {\n            path.startsWith("\/product\/") -> {\n                val productId = uri.lastPathSegment\n                navigateToProduct(productId)\n            }\n            path.startsWith("\/profile\/") -> {\n                val username = uri.lastPathSegment\n                navigateToProfile(username)\n            }\n            path.startsWith("\/promo") -> {\n                val code = uri.getQueryParameter("code")\n                navigateToPromo(code)\n            }\n            else -> {\n                \/\/ Fallback: open the home screen\n                navigateToHome()\n            }\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Two things to notice. First, you must handle the intent in both onCreate<\/code> (cold start) and onNewIntent<\/code> (app already running). If you skip onNewIntent<\/code>, links tapped while the app is in the background will be silently ignored. Second, always include a fallback for unrecognized paths so users do not land on a blank screen.<\/p>\n\n\n\n
      Jetpack Compose with Navigation<\/h3>\n\n\n\n
      If you are using Jetpack Compose<\/a> with the Navigation component, you can declare deep links directly in your navigation graph:<\/p>\n\n\n\n
      @Composable\nfun AppNavigation() {\n    val navController = rememberNavController()\n\n    NavHost(\n        navController = navController,\n        startDestination = "home"\n    ) {\n        composable("home") {\n            HomeScreen()\n        }\n\n        composable(\n            route = "product\/{productId}",\n            arguments = listOf(navArgument("productId") { type = NavType.StringType }),\n            deepLinks = listOf(\n                navDeepLink {\n                    uriPattern = "https:\/\/yourdomain.com\/product\/{productId}"\n                }\n            )\n        ) { backStackEntry ->\n            val productId = backStackEntry.arguments?.getString("productId")\n            ProductScreen(productId = productId)\n        }\n\n        composable(\n            route = "profile\/{username}",\n            deepLinks = listOf(\n                navDeepLink {\n                    uriPattern = "https:\/\/yourdomain.com\/profile\/{username}"\n                }\n            )\n        ) { backStackEntry ->\n            val username = backStackEntry.arguments?.getString("username")\n            ProfileScreen(username = username)\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
      The Navigation component handles the URL parsing and argument extraction for you. When the activity receives an App Link intent, the NavHost matches the URI pattern and navigates to the correct composable. You still need the intent filter in your manifest; the navDeepLink<\/code> declaration only handles routing within Compose, not the system-level registration.<\/p>\n\n\n\n
      Extracting Query Parameters<\/h3>\n\n\n\n
      Deep links often carry data as query parameters. Here is how to extract them:<\/p>\n\n\n\n
      private fun handleDeepLink(intent: Intent) {\n    val uri = intent.data ?: return\n\n    \/\/ For a URL like: https:\/\/yourdomain.com\/referral?code=ABC123&source=email\n    val referralCode = uri.getQueryParameter("code")      \/\/ "ABC123"\n    val source = uri.getQueryParameter("source")           \/\/ "email"\n    val allParams = uri.queryParameterNames                \/\/ Set<String>\n\n    \/\/ Use the extracted data\n    if (referralCode != null) {\n        applyReferralCode(referralCode, source)\n    }\n}\n<\/code><\/pre>\n\n\n\n
      App Links Verification Details<\/h2>\n\n\n\n
      Understanding how Android verifies App Links helps you avoid common pitfalls.<\/p>\n\n\n\n
      Verification Timing<\/h3>\n\n\n\n
      On Android 11 and earlier, verification happens once: when the app is installed or updated. If your assetlinks.json<\/code> file is not ready at install time, verification fails and stays failed until the user reinstalls the app.<\/p>\n\n\n\n
      On Android 12+, the system uses a background domain verification process<\/a> that can re-check domains. You can also manually trigger re-verification:<\/p>\n\n\n\n
      # Reset verification state (Android 12+)\nadb shell pm set-app-links --package com.example.myapp 0 all\n\n# Trigger re-verification\nadb shell pm verify-app-links --re-verify com.example.myapp\n<\/code><\/pre>\n\n\n\n
      Subdomain Handling<\/h3>\n\n\n\n
      Each subdomain is treated as a separate domain. If your manifest declares app.yourdomain.com<\/code>, Android will check https:\/\/app.yourdomain.com\/.well-known\/assetlinks.json<\/code>. It will not fall back to yourdomain.com<\/code>. You must host the file on the exact subdomain listed in your intent filter.<\/p>\n\n\n\n
      Server Requirements<\/h3>\n\n\n\n
      Your server must meet these requirements for the assetlinks.json<\/code> file:<\/p>\n\n\n\n