Deep linking · Guide
Testing Your Deep Links on iOS and Android
Test every route in every state that changes the outcome: app installed or not, host verified or not, and the context the tap comes from. Use the platform tools to read verification state, then tap real links on real devices and record what happened, with the date, build and device.
In short
- Android: wait at least 20 seconds after install, then read pm get-app-links; re-run verification with pm verify-app-links --re-verify.
- Apple: swcutil checks the file and URL matching; a sysdiagnose shows site approval; Developer Mode adds diagnostics.
- Test taps from another app, from a different domain and from your own domain, plus a typed address.
- Record results as observations with date and build; never present a planned outcome as a result.
The test matrix
Test every link a campaign still prints, including old short links from a retired service, as the Dynamic Links migration guide describes. A route can behave differently on the same phone depending on three things. Test each combination that applies to your link:
| Dimension | Values to test | Why |
|---|---|---|
| Install state | Installed, not installed, installed after the link was opened | Without the app the link must reach a working page |
| Verification | Verified, not yet verified, file changed recently | Unverified Android web links usually open in the browser or a chooser |
| Tap context | Another app (email, notes, chat), a different domain, your own domain, a typed address | iOS keeps same-domain taps and typed addresses in the browser |
| Platform | Current and older Android versions, current iOS | Android 11 and lower require every host to verify |
| Market | A licensed location and one where the app is not offered | The app is geo-restricted; the web page must still work |
Android checks
- Confirm the host list. Collect every intent filter URL with an http or https scheme, a host, the VIEW action and the BROWSABLE category. Each host needs a file.
- Read what Google sees. Query the Digital Asset Links API for each host:
https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urls - Install and wait. "Make sure you wait at least 20 seconds after installation of your app to allow for the system to complete the verification process."
- Read the result.
adb shell pm get-app-links PACKAGE_NAME. Each host should readverified. - Re-run after a fix. Reset and verify again:
adb shell pm set-app-links --package PACKAGE_NAME 0 alladb shell pm verify-app-links --re-verify PACKAGE_NAME
The troubleshooting guide calls the re-verify command "the most reliable way to test changes." - Open a link.
adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://www.example.com/events/123" - On Android 17 and later,
am start --debug-linkshows which apps, filters and dynamic rules match a URL.
One caution from Android's test guide: "If a user changes the app link settings for an app before verification is complete, you may see a false positive for a successful verification, even though verification has failed." Use a clean device or reset the app's link settings before each run. Why the two platforms pick up file changes at different speeds is covered in the comparison of the two association files.
Apple checks
- Entitlement. In Xcode's Signing & Capabilities tab, confirm Associated Domains lists
applinks:entries for every domain, with no port numbers. - File download. On a Mac,
sudo swcutil dl -d www.example.comconfirms the file downloads. - Pattern match.
sudo swcutil verify -d www.example.com -j ./apple-app-site-association -u https://www.example.com/events/123checks a URL against a local copy of the file; an excluded path reports a blocked match. - Device state. Capture a sysdiagnose with the app installed, open
swcutil_show.txtand find your app ID. "Site/Fmwk Approval" should read approved. - Developer Mode. Turn on Developer Mode, then Settings, Developer, Universal Links, Associated Domains Development, and use Diagnostics to test a full URL.
- Tap test. Paste the link into Notes and tap it; long-press to check the open-in-app option. Then tap it from a page on a different domain, and from your own domain, where Safari keeps it by design.
The evidence log
Record each tap as an observation, not a promise:
Example log row (invented values)
2026-10-28 · Android 15 · build 4.12.0 (release-signed) · installed · tapped in email app · https://www.example.com/events/123 · opened event screen · tester initials
Keep failures as carefully as passes, with the fix and the re-test date. The route inspector exports a link's parts with your notes, and the implementation checklist exports the release checklist. If a step fails, the taxonomy of broken app links maps symptoms to causes, and the note on links that open the browser separates faults from designed behavior.
Questions
How long should we wait after installing before checking Android verification?
Android's test guide says to wait at least 20 seconds after installation so the system can complete verification.
Should iOS tests run on a fresh install?
Yes, at least once per release, because devices fetch the association file at install and then about once a week.
What should a deep link test record keep?
The exact URL, the operating system and version, the app build, whether the app was installed, where the tap came from, what happened, the date, and who tested. Export it from the route inspector or the checklist.
Sources
- Android Developers, Verify App Links, last updated October 23, 2026.
- Android Developers, Test App Links, last updated October 16, 2026.
- Android Developers, Troubleshoot App Links, last updated October 23, 2026.
- Apple Developer, TN3155: Debugging universal links, latest revision May 15, 2025.
- Google Developers, Digital Asset Links, linked from Android's Configure page; not fetched by us.
How we choose and date sources: data sources.