Deep link tester: adb, xcrun and Universal Link checks
This tool builds the test for one deep link: the adb am start and pm get-app-links commands, xcrun simctl openurl, the Digital Asset Links API and Apple CDN URLs, an intent:// link and an HTML test page. Paste the file your server returns to check the package, fingerprints, app ID and path, and use the table to diagnose why a link opens the browser.
Updated
Web link
www.example.com
Path /products/42?ref=email. Needs assetlinks.json on Android and an AASA file on iOS.
Test commands
# Deep link test script. Run line by line; nothing here changes your server. # Link: https://www.example.com/products/42?ref=email # ---- Android (adb, device or emulator connected) ---- adb shell am start -W -a android.intent.action.VIEW -d "https://www.example.com/products/42?ref=email" com.example.myapp adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://www.example.com/products/42?ref=email" # Verification (Android 12+). Wait about 20 seconds after install; after --re-verify wait a few minutes. adb shell pm set-app-links --package com.example.myapp 0 all adb shell pm verify-app-links --re-verify com.example.myapp adb shell pm get-app-links com.example.myapp adb shell pm get-app-links --user cur com.example.myapp adb shell dumpsys package domain-preferred-apps # Only if the app targets Android 11 or lower and you want the new verification process: # adb shell am compat enable 175408749 com.example.myapp # Android 17 and later: shows why the link resolved the way it did adb shell am start --debug-link -a android.intent.action.VIEW -d "https://www.example.com/products/42?ref=email" # ---- Server: does Android's file load cleanly? ---- curl -sS -o /dev/null -D - https://www.example.com/.well-known/assetlinks.json # Google's view of the file (open in a browser): # https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urls # ---- iOS ---- xcrun simctl openurl booted "https://www.example.com/products/42?ref=email" # Apple's CDN copy (iOS 14+ apps read this, not your server) curl -sS -D - https://app-site-association.cdn-apple.com/a/v1/www.example.com curl -sS -D - https://www.example.com/.well-known/apple-app-site-association curl -sS -o /dev/null -D - -A "MyAgent-Bot/*" https://www.example.com/.well-known/apple-app-site-association # On a Mac: can the file be downloaded, and does this URL match it? (swcutil ships with macOS) sudo swcutil dl -d www.example.com # sudo swcutil verify -d www.example.com -j ./apple-app-site-association.json -u "https://www.example.com/products/42?ref=email" # On a real iPhone: paste the link into Notes, tap it, or long-press it for the Open options. # Typing the link into Safari's address bar never opens the app (Apple, TN3155).
- Android: open the link
- adb shell am start -W -a android.intent.action.VIEW -d "https://www.example.com/products/42?ref=email" com.example.myapp-W waits for launch and prints the activity. With the package, it targets your app directly, so it tests the intent filter, not verification.
- Android: open as a browser would
- adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://www.example.com/products/42?ref=email"No package: Android picks the handler. If your app opens without a dialog, the link is verified.
- Android: re-run verification (Android 12+)
- adb shell pm verify-app-links --re-verify com.example.myappReset first with: adb shell pm set-app-links --package com.example.myapp 0 all. Wait a few minutes before reading the result.
- Android: read the verification state
- adb shell pm get-app-links com.example.myappverified is good. none means wait and retry; legacy_failure and 1024 or higher mean the check failed.
- Android: see link-handling settings
- adb shell pm get-app-links --user cur com.example.myappShows whether the user has the app approved for each domain.
- Android 17: explain how the link resolved
- adb shell am start --debug-link -a android.intent.action.VIEW -d "https://www.example.com/products/42?ref=email"Prints the matching apps, the manifest filter and the verification state under 'App Link Resolution Debug'. Starting in Android 17 only.
- Google Digital Asset Links API check
- https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urlsOpen it in a browser. A statements list with your package and fingerprint means Google can read the file.
- Check the assetlinks.json response headers
- curl -sS -o /dev/null -D - https://www.example.com/.well-known/assetlinks.jsonWant: HTTP 200, content-type application/json, and no Location header (no 301 or 302).
- Apple CDN copy of your AASA
- https://app-site-association.cdn-apple.com/a/v1/www.example.comiOS 14 and later ask Apple's CDN, not your server. Blank or 404 means the CDN can't reach your file. The CDN URL is observed behaviour: Apple's pages describe the CDN without printing this URL.
- Your AASA, direct
- curl -sS -D - https://www.example.com/.well-known/apple-app-site-associationWant: HTTP 200, no 301 or 302, a JSON body, and the same answer for any user agent.
- AASA with an unusual user agent
- curl -sS -o /dev/null -D - -A "MyAgent-Bot/*" https://www.example.com/.well-known/apple-app-site-associationApple's TN3155 uses this to prove your server answers every user agent, not only browsers.
- iOS Simulator: open the link
- xcrun simctl openurl booted "https://www.example.com/products/42?ref=email"Xcode's own help describes it as 'Open a URL in a device' (xcrun simctl help openurl). Boot a simulator with the app installed first.
- Android intent:// link for Chrome
- intent://www.example.com/products/42?ref=email#Intent;scheme=https;package=com.example.myapp;S.browser_fallback_url=https%3A%2F%2Fwww.example.com%2Fproducts%2F42%3Fref%3Demail;endOpens the app if installed, else the fallback web page. Chrome needs a user tap; it won't launch an app from a timer or script without a gesture. The #fragment of the original link is dropped.
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Android: link opens the browser, not the app | android:autoVerify="true" missing from the intent filter, or the filter lacks the VIEW action, DEFAULT and BROWSABLE categories, or an http/https data scheme | Compare the manifest with the intent filter on the Android App Links page; then adb shell pm get-app-links PACKAGE | Add autoVerify, BROWSABLE and DEFAULT, rebuild, reinstall, wait about 20 seconds, then re-verify |
| Android: pm get-app-links shows none | Verification hasn't run or finished yet | Wait a few minutes after --re-verify, then read the state again | Run pm set-app-links --package PKG 0 all, then pm verify-app-links --re-verify PKG on a device that is online |
| Android: state is legacy_failure or 1024 or higher | The check failed: wrong fingerprint, redirect, wrong content type, or file unreachable | Open the Digital Asset Links API URL for the host; run curl -D - on the assetlinks.json URL | Fix the file or the hosting, then re-verify; Android says 1024+ is a device-specific error code |
| Android: works for the debug build, not the Play build | Wrong SHA-256: Play App Signing re-signs the app, so users get a different certificate from your upload key | Compare the fingerprint in pm get-app-links with the file; Play Console shows the app signing key | Add the app signing key's SHA-256 to sha256_cert_fingerprints (the fingerprint list allows several) |
| Android: assetlinks.json fetched but rejected | The URL redirects (301 or 302), for example http to https or apex to www | curl -sS -o /dev/null -D - https://HOST/.well-known/assetlinks.json shows a Location header | Serve the file with HTTP 200 directly on the exact host named in the intent filter |
| Android: assetlinks.json has the right content but fails | Wrong content type, or served only over http, or blocked by a login, WAF or robots rule | Check the content-type header says application/json and the URL works over HTTPS | Serve application/json over HTTPS with no authentication |
| Android: one subdomain works, another doesn't | Each host in the intent filters needs its own file | List every android:host with autoVerify; test each in the API URL | Publish assetlinks.json on every host |
| Android: another app opens instead | Only one app can be verified per domain, or the user chose a default | pm get-app-links --user cur PKG shows the selection state; dumpsys package domain-preferred-apps | Remove the other app, or have the user clear its Open by default setting |
| Android: custom scheme asks 'open with' | Another app declares the same scheme, or BROWSABLE is missing | adb shell am start -W -a android.intent.action.VIEW -d "myapp://…" | Use App Links on your own domain; keep custom schemes for links from your own apps |
| Android: intent:// link does nothing | Chrome won't launch an app from a script or timer without a user gesture | Tap a real <a> link on the test page | Trigger it from a tap, and set S.browser_fallback_url for devices without the app |
| iOS: link opens Safari, not the app | The tap was on the same domain you are browsing; Safari keeps same-domain links in the browser | Apple's TN3155: tap from Notes, Messages or another app instead | Link from a different domain or a subdomain with its own AASA and applinks entry |
| iOS: typing the link in Safari does nothing | Typing in the address bar is direct navigation and never opens the app | Paste the link into Notes, tap or long-press it | Test from another app, as Apple's TN3155 advises |
| iOS: AASA download fails (403, 404, or 301/302) | Redirects are not supported for the AASA file, or the host blocks some IPs or user agents | curl -v the file and curl -A "MyAgent-Bot/*" it; check the Apple CDN URL | Serve the file at https://HOST/.well-known/apple-app-site-association with no redirect, open to all IPs and agents |
| iOS: AASA content type or extension | Apple says to name the file apple-app-site-association with no extension | Check the URL has no .json and the headers show a 200 with a JSON body | Rename it; application/json is the type Apple's own CDN returned for a working site. Apple's pages say nothing stricter |
| iOS: works for example.com, not www.example.com | applinks:example.com covers the root domain only; each subdomain needs its own entry and file | Compare the entitlement list with the hosts you link to | Add applinks:www.example.com and host the file there as well |
| iOS: matches in the file but still opens the browser | The app ID prefix is wrong (Team ID missing or wrong), or formats are mixed | Look at appIDs for TEAMID.bundle.id; run swcutil verify -d HOST -j file -u URL | Use exactly TEAMID.bundleID, and use components or paths, not both, per entry |
| iOS: edit made, old behaviour continues | Apple's CDN caches the file; devices recheck about weekly; there is no invalidation | Request the CDN URL and compare with your file | Reinstall the app to fetch a newer copy; use ?mode=developer on the entitlement while developing |
| iOS: link started from your own app doesn't open the app | UIApplication.open with a universal link to your own site doesn't launch your app | Apple's docs say links opened by those methods won't open in your app | Navigate in code instead of opening your own universal link |
- Associated Domains entitlement for this link: applinks:www.example.com. Don't add a port: Apple says a domain with a port number in applinks will not open the app. Each subdomain needs its own entry and its own AASA file.
- For developing against a server Apple's CDN can't reach, add ?mode=developer to the entitlement: applinks:www.example.com?mode=developer. That makes the device fetch the file straight from your domain.
How do you test a deep link end to end?
A deep link has three parts to prove: the app declares it (an Android intent filter or an iOS Associated Domains entitlement), your server confirms it (assetlinks.json for Android App Links, apple-app-site-association for Universal Links), and the device actually routes the tap to the app. Android on API 23 and later verifies hosts for filters marked android:autoVerify="true" by fetching https://HOST/.well-known/assetlinks.json; Android 12 and later let you re-run that on a test device with pm verify-app-links --re-verify, and read the result with pm get-app-links.
On iOS, since iOS 14 devices don't ask your server: they ask an Apple-managed CDN, which fetched your file within 24 hours of the app being installed, and devices re-check about weekly. That's why a correct file can still show old behaviour, and why the checks here include the CDN URL. The usual failures are redirects (neither platform follows them for these files), a wrong signing fingerprint or Team ID, a missing subdomain entry, and tapping a same-domain link inside Safari, which stays in the browser by design.
This tool builds the commands for your link, package and bundle ID. It can't fetch your files from the page because browsers block reading other sites, so you run curl and paste the response back if you want a check of the package, fingerprints, app ID and whether your link matches a rule.
To write the Android file this tester checks, use the assetlinks.json generator.
To write the iOS file, use the apple-app-site-association generator.
To find the right SHA-256 for a debug, upload or Play signing key, use the Android keystore SHA helper.
Which failure matches what you see?
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Android: link opens the browser, not the app | android:autoVerify="true" missing from the intent filter, or the filter lacks the VIEW action, DEFAULT and BROWSABLE categories, or an http/https data scheme | Compare the manifest with the intent filter on the Android App Links page; then adb shell pm get-app-links PACKAGE | Add autoVerify, BROWSABLE and DEFAULT, rebuild, reinstall, wait about 20 seconds, then re-verify |
| Android: pm get-app-links shows none | Verification hasn't run or finished yet | Wait a few minutes after --re-verify, then read the state again | Run pm set-app-links --package PKG 0 all, then pm verify-app-links --re-verify PKG on a device that is online |
| Android: state is legacy_failure or 1024 or higher | The check failed: wrong fingerprint, redirect, wrong content type, or file unreachable | Open the Digital Asset Links API URL for the host; run curl -D - on the assetlinks.json URL | Fix the file or the hosting, then re-verify; Android says 1024+ is a device-specific error code |
| Android: works for the debug build, not the Play build | Wrong SHA-256: Play App Signing re-signs the app, so users get a different certificate from your upload key | Compare the fingerprint in pm get-app-links with the file; Play Console shows the app signing key | Add the app signing key's SHA-256 to sha256_cert_fingerprints (the fingerprint list allows several) |
| Android: assetlinks.json fetched but rejected | The URL redirects (301 or 302), for example http to https or apex to www | curl -sS -o /dev/null -D - https://HOST/.well-known/assetlinks.json shows a Location header | Serve the file with HTTP 200 directly on the exact host named in the intent filter |
| Android: assetlinks.json has the right content but fails | Wrong content type, or served only over http, or blocked by a login, WAF or robots rule | Check the content-type header says application/json and the URL works over HTTPS | Serve application/json over HTTPS with no authentication |
| Android: one subdomain works, another doesn't | Each host in the intent filters needs its own file | List every android:host with autoVerify; test each in the API URL | Publish assetlinks.json on every host |
| Android: another app opens instead | Only one app can be verified per domain, or the user chose a default | pm get-app-links --user cur PKG shows the selection state; dumpsys package domain-preferred-apps | Remove the other app, or have the user clear its Open by default setting |
| Android: custom scheme asks 'open with' | Another app declares the same scheme, or BROWSABLE is missing | adb shell am start -W -a android.intent.action.VIEW -d "myapp://…" | Use App Links on your own domain; keep custom schemes for links from your own apps |
| Android: intent:// link does nothing | Chrome won't launch an app from a script or timer without a user gesture | Tap a real <a> link on the test page | Trigger it from a tap, and set S.browser_fallback_url for devices without the app |
| iOS: link opens Safari, not the app | The tap was on the same domain you are browsing; Safari keeps same-domain links in the browser | Apple's TN3155: tap from Notes, Messages or another app instead | Link from a different domain or a subdomain with its own AASA and applinks entry |
| iOS: typing the link in Safari does nothing | Typing in the address bar is direct navigation and never opens the app | Paste the link into Notes, tap or long-press it | Test from another app, as Apple's TN3155 advises |
| iOS: AASA download fails (403, 404, or 301/302) | Redirects are not supported for the AASA file, or the host blocks some IPs or user agents | curl -v the file and curl -A "MyAgent-Bot/*" it; check the Apple CDN URL | Serve the file at https://HOST/.well-known/apple-app-site-association with no redirect, open to all IPs and agents |
| iOS: AASA content type or extension | Apple says to name the file apple-app-site-association with no extension | Check the URL has no .json and the headers show a 200 with a JSON body | Rename it; application/json is the type Apple's own CDN returned for a working site. Apple's pages say nothing stricter |
| iOS: works for example.com, not www.example.com | applinks:example.com covers the root domain only; each subdomain needs its own entry and file | Compare the entitlement list with the hosts you link to | Add applinks:www.example.com and host the file there as well |
| iOS: matches in the file but still opens the browser | The app ID prefix is wrong (Team ID missing or wrong), or formats are mixed | Look at appIDs for TEAMID.bundle.id; run swcutil verify -d HOST -j file -u URL | Use exactly TEAMID.bundleID, and use components or paths, not both, per entry |
| iOS: edit made, old behaviour continues | Apple's CDN caches the file; devices recheck about weekly; there is no invalidation | Request the CDN URL and compare with your file | Reinstall the app to fetch a newer copy; use ?mode=developer on the entitlement while developing |
| iOS: link started from your own app doesn't open the app | UIApplication.open with a universal link to your own site doesn't launch your app | Apple's docs say links opened by those methods won't open in your app | Navigate in code instead of opening your own universal link |
How to test a deep link on Android and iOS
- 1Enter the link and your IDsPaste the exact link you plan to send, your Android package name, iOS bundle ID and Apple Team ID.
- 2Check the files from the serverRun the curl commands and open the Digital Asset Links API URL and the Apple CDN URL. Look for HTTP 200, no redirect, and your IDs in the body.
- 3Fire the link on a deviceRun the adb commands on an Android 12 or newer device or emulator. On iOS, use xcrun simctl openurl on a simulator, then paste the link into Notes on a real iPhone and tap it.
- 4Read the result and fixIf it fails, match your symptom in the table. Paste the file you served to check the package, fingerprints, app ID and whether the link's path matches a rule.
Frequently asked questions
Why does my deep link work with adb but not when tapped in a browser?
How long should I wait after installing before testing Android App Links?
What does the Apple CDN URL show me?
Why doesn't a Universal Link open my app when I tap it inside my own website?
Do I need both an intent:// link and a normal https link?
Can I verify a custom scheme link like myapp://?
Sources
- Android Developers: Verify Android App Links (autoVerify, pm commands, verification states, update latency) (checked 11 Nov 2026)
- Android Developers: Create deep links to app content (intent filters, am start test) (checked 11 Nov 2026)
- Android Developers: Test App Links (Digital Asset Links API URL, dumpsys, --debug-link) (checked 11 Nov 2026)
- Android Developers: Configure Digital Asset Links (hosting rules) (checked 11 Nov 2026)
- Apple Developer: Supporting associated domains (file location, CDN, alternate modes) (checked 11 Nov 2026)
- Apple Developer: Allowing apps and websites to link to your content (same-domain behaviour) (checked 11 Nov 2026)
- Apple Developer: TN3155, Debugging universal links (checked 11 Nov 2026)
- Chrome for Developers: Android Intents (intent:// syntax and fallback) (checked 11 Nov 2026)
Need a custom dev tool for your team?
We build internal tools, dashboards, APIs, and SaaS platforms. If you can describe it, we can ship it.
Built by CountryDevs · No signup · No ads · We count visits, never what you enter