Android App Links: The Complete Deep Linking & Fallback Testing Guide (2026)

Deep links that "sometimes open the app" are broken. That qualifier — sometimes — means the setup is partially working or intermittently failing, and you are losing users to the browser on every failure without a log entry, a crash report, or any visible signal that anything went wrong. The user sees a web page instead of the app screen they expected. Most of them do not retry. They are gone.

Android App Links — the HTTP URL-based deep linking mechanism introduced in Android 6.0 and significantly evolved through Android 12 and Android 15 — are the correct modern solution for this class of problem. When properly configured, a verified App Link opens your app instantly, on the right screen, with the correct content loaded, with no user choice required. When misconfigured, it fails silently in ways that are invisible unless you specifically test for them.

This guide is the complete implementation and testing reference for Android App Links in 2026 — covering the three-component architecture, the assetlinks.json file in full detail, every known failure mode and its fix, the fallback chain across Android versions, Dynamic App Links introduced in Android 15, the aftermath of Firebase Dynamic Links' deprecation, and the exact ADB commands and test matrix your QA team should run before every release that touches deep linking.

The Three Core Components of Android App Links

Android App Links require three components to work correctly. Missing or misconfiguring any one of them causes silent failures. All three must be correct simultaneously — and when they are, Android routes matching HTTP URLs directly to your app without user interaction.

Part One: The AndroidManifest.xml Intent Filter

The intent filter in your manifest tells Android which URLs your app wants to handle. For App Links — as opposed to basic deep links — the critical element is android:autoVerify="true", which tells Android to verify domain ownership at install time rather than just presenting a disambiguation dialog.

<activity android:name=".MainActivity">

    <!-- Standard intent filter for launcher -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- App Links intent filter — autoVerify triggers domain verification -->
    <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" />

        <!-- Must be https for App Links — http alone is insufficient -->
        <data
            android:scheme="https"
            android:host="example.com"
            android:pathPrefix="/product" />
    </intent-filter>

    <!-- Separate filter for www subdomain — Android treats subdomains as separate hosts -->
    <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="www.example.com"
            android:pathPrefix="/product" />
    </intent-filter>

</activity>

Part Two: The assetlinks.json File — The Most Failure-Prone Component

The Digital Asset Links file is the contract between your domain and your app. It must be hosted at exactly https://yourdomain.com/.well-known/assetlinks.json, served with the correct content-type header, without any HTTP redirect, and containing the correct package name and SHA-256 certificate fingerprint.

Every one of those requirements is a potential failure point. A redirect from HTTP to HTTPS, a CDN caching the wrong content-type, or an incorrect certificate fingerprint (using the debug signing fingerprint in a production build, for example) will all cause the verification to fail — silently, with no visible error on the device, only a fallback to the browser or disambiguation dialog when the link is tapped.

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.yourapp",

        // SHA-256 fingerprint of your PRODUCTION signing certificate
        // Get it with: keytool -list -v -keystore your-key.jks
        // Or from Google Play Console → App Integrity → App signing key certificate
        "sha256_cert_fingerprints": [
            "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",
            // Optional: include debug fingerprint for development testing
            "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:AB"
        ]
    }
},
// Android 15+: Dynamic App Links configuration (optional)
{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.yourapp",
        "sha256_cert_fingerprints": ["AB:CD:EF:..."],
        "dynamic_app_deep_link_components": [{
            "include_patterns": ["/product/*", "/profile/*"],
            "exclude_patterns": ["/product/admin"]
        }]
    }
}]

How to Get Your SHA-256 Fingerprint

There are three sources for the correct fingerprint, and using the wrong one is a very common misconfiguration error.

# Method 1: From your keystore file (local signing)
keytool -list -v -keystore /path/to/your-release.jks -alias your-alias
# Look for: SHA256: AB:CD:EF:... in the output

# Method 2: From Google Play App Signing (if using Play-managed signing)
# Go to: Play Console → Your App → Setup → App Integrity → App signing key certificate
# Copy the SHA-256 certificate fingerprint shown there
# ⚠️  This is the ONLY correct fingerprint when using Play App Signing
# Your local keystore fingerprint will NOT match — verification will fail

# Method 3: From an installed APK (verify what's actually deployed)
apksigner verify --print-certs /path/to/your-release.apk
# Or: keytool -printcert -jarfile /path/to/your-release.apk

# Verify your assetlinks.json is live and correct:
curl -v https://yourdomain.com/.well-known/assetlinks.json
# Confirm: HTTP/2 200, Content-Type: application/json, no redirects in the chain

Part Three: Server and CDN Requirements for assetlinks.json

The file must be served exactly as the Android system expects it. Deviations that seem minor — a redirect, a slightly wrong content-type, a CDN caching header — fail the verification silently.

1. 1

   Serve at exactly https://yourdomain.com/.well-known/assetlinks.json — no redirects

   The Android system fetches this path directly. If your server redirects HTTP to HTTPS, or www to non-www, the fetch fails. The file must be available on HTTPS at the canonical path without any redirect in the chain. If your CDN or server adds a redirect on /.well-known/ paths, you must add an explicit exception rule for that directory. On Cloudflare, add a Page Rule to exclude /.well-known/* from "Always Use HTTPS" redirect enforcement.

2. 2

   Content-Type header must be application/json

   Some servers serve .json files with a text/plain content-type or no content-type at all. The Android verification system requires application/json. For Firebase Hosting, add explicit headers to your firebase.json. For Vercel, add a headers rule in next.config.js. For Nginx, add a types block or explicit add_header for the .well-known directory.

3. 3

   File size must be under 128 KB

   If your app has many hosts and many certificates, the assetlinks.json file can grow large. The Android system has a 128 KB size limit. Files over this limit are rejected. If you are approaching this limit, use wildcards in your pathPrefix values and consolidate entries rather than listing every individual path.

4. 4

   Ensure the file is served from the exact domain — not a CDN subdomain

   The Android system queries https://yourdomain.com/.well-known/assetlinks.json — the same domain declared in your intent filter's android:host. If your CDN routes the file from a different origin domain, or if a reverse proxy serves it from a different hostname, the verification fails. The response must come from the canonical domain as it appears in your manifest.

{
    "hosting": {
        "headers": [{
            "source": "/.well-known/assetlinks.json",
            "headers": [{
                "key": "Content-Type",
                "value": "application/json"
            }]
        }, {
            "source": "/.well-known/apple-app-site-association",
            "headers": [{
                "key": "Content-Type",
                "value": "application/json"
            }]
        }]
    }
}

Part Four: The Fallback Chain — What Actually Happens When Verification Fails

Understanding the fallback chain is essential for writing an adequate test plan. What Android does when App Link verification fails changed significantly in Android 12, and the change has ongoing implications for apps that have not been updated or tested since.

Part Five: Dynamic App Links — Android 15's Server-Side Control

Android 15 introduced Dynamic App Links, one of the most significant changes to the App Links system since its introduction. Previously, assetlinks.json was used primarily for basic domain verification. With Dynamic App Links, it becomes a configuration file that can update your app's deep link behaviour without requiring a new app release.

Android devices with Google services periodically refresh your assetlinks.json file and apply new deep link rules dynamically. This means you can add, modify, or exclude URL patterns server-side — and those changes propagate to user devices without requiring them to update the app.

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.yourapp",
        "sha256_cert_fingerprints": ["AB:CD:EF:..."],
        "dynamic_app_deep_link_components": [{
            // Paths that SHOULD open the app
            "include_patterns": [
                "/product/*",
                "/profile/*",
                "/order/*"
            ],
            // Paths that should NEVER open the app even if they match
            "exclude_patterns": [
                "/product/admin",
                "/profile/settings/delete"
            ]
        }]
    }
}]

Practical applications of Dynamic App Links include: immediately excluding a path from App Link handling when a feature is sunset (without waiting for a release cycle), adding new product categories or sections to App Link coverage as they launch, and A/B testing deep link destinations by updating server-side routing rules. The dynamic refresh is not instantaneous — devices periodically fetch the file based on their own schedules — so Dynamic App Links are appropriate for non-time-critical configuration changes, not real-time routing decisions.

Part Six: Firebase Dynamic Links Is Dead — What to Do Now

Firebase Dynamic Links was deprecated in August 2023 and shut down completely in 2025. Any app still using Firebase Dynamic Links has broken deep links — affected users are experiencing failures silently, often without the development team knowing because the links resolve without crashing the app.

Part Seven: The Complete Test Matrix

Deep link behaviour varies across Android versions, install states, entry points, and browser environments. Testing only the happy path — link tapped on a device where the app is installed and verification passed — covers one of the roughly twelve distinct scenarios that affect users in the wild. Here is the complete matrix.

ADB Commands for Development Testing

# Test a specific App Link URL (replace with your domain and path)
adb shell am start -W -a android.intent.action.VIEW \
    -d "https://yourdomain.com/product/123" com.yourpackage.name

# Expected: App launches directly to product screen
# Failure: Browser opens or disambiguation dialog appears

# Verify the assetlinks.json file is correctly served and parseable
curl -v https://yourdomain.com/.well-known/assetlinks.json
# Confirm: HTTP/2 200 OK, Content-Type: application/json, no redirects

# Check App Link verification status on a connected device (Android Studio)
# Tools → App Links Assistant → Verify Asset Links

# Force re-verification after changing assetlinks.json (development only)
# Uninstall the app, then reinstall — verification only runs at install/update
adb uninstall com.yourpackage.name
# Reinstall via Android Studio or adb install

# Check Android's verification log for your app
adb shell pm get-app-links --user cur com.yourpackage.name
# Look for: "verified" = true for each host

# Test fallback: what happens when the app is NOT installed
adb uninstall com.yourpackage.name
adb shell am start -a android.intent.action.VIEW -d "https://yourdomain.com/product/123"
# Expected: Opens in browser — confirm your web fallback page is correct

Full Test Matrix

The Complete Failure Mode Checklist

• ✕

  Wrong SHA-256 fingerprint — most common cause of production failure. Using the local keystore fingerprint when the app is distributed via Play App Signing. The correct fingerprint is in Play Console → App Integrity, not in your local .jks file. Verification works in local debug builds and fails in production. Fix: update assetlinks.json with the Play App Signing certificate fingerprint.

• ✕

  HTTP redirect on the assetlinks.json path. The most common CDN issue. Cloudflare's "Always Use HTTPS" and similar redirect rules intercept the /.well-known/ path. Android's verification system does not follow redirects. Fix: add a Page Rule or routing exception that serves /.well-known/assetlinks.json directly from origin without redirect.

• ✕

  Wrong Content-Type header on assetlinks.json. Servers serving .json files as text/plain cause verification failure. Add explicit content-type configuration to your web server, CDN, or hosting platform for the /.well-known/ directory.

• ✕

  Missing host entries in assetlinks.json. If your manifest declares android:host="example.com" and android:host="www.example.com", both must have their own assetlinks.json at their respective paths. Android verifies each host independently.

• ✕

  Overlapping intent-filter paths across activities. If two activities in your app both have intent filters that match the same URL pattern, Android may show a disambiguation dialog or fail to determine a single handler. Intent filters across activities must not overlap. The Android Docs troubleshooting guide identifies this as a common disambiguation dialog trigger even when App Links are otherwise correctly configured.

• ✕

  Not reinstalling after fixing verification config during development. Android verification runs only at install or update time. Changes to assetlinks.json or the manifest do not take effect until the app is reinstalled. Uninstall and reinstall — do not simply rebuild and run — after making any verification-related change. Server-side cache may add additional delay; retry after a few hours if the issue persists after reinstall.

• ✕

  Email marketing tracking wrappers. SendGrid, HubSpot, Mailchimp, and similar platforms wrap all tracked links through their own redirect domains. A link to https://yourapp.com/product/123 becomes https://click.sendgrid.net/wf/click?upn=.... Android only trusts your verified domain. Tracking-wrapped links will always open in the browser — not the app. This is expected and by design, not a bug in your setup.