How to test Universal Links and App Links (iPhone, Android and the simulator)
Universal Links and App Links often work in one place and fail in another. How to test them properly: on a real iPhone, in the iOS simulator, with adb on Android, inside Instagram and other in-app browsers, and after a fresh install, plus the checks that tell you why a link opened the browser.
· DL2App · 6 min read
Universal Links (iOS) and App Links (Android) have a habit of working on your desk and failing for your users. Usually the setup is fine and the test was wrong: a link typed into the address bar, a phone that cached an old file, or an in-app browser that never hands links to the system.
This is how to test them so the result means something, and how to find out why a link opened the browser instead of your app.
The short answer
- Check the files first. If
apple-app-site-associationorassetlinks.jsonis wrong, nothing else matters. Our free link checker fetches both the way phones do. - Tap links, don't type them. A link typed or pasted into Safari or Chrome's address bar never opens the app. Tap it from Notes, Messages or an email.
- Test where people really tap: Messages, Mail, WhatsApp, and inside Instagram and TikTok, where links behave differently.
- Test with the app installed and not installed. The second case is where store redirects and deferred deep linking get tested.
Before you touch a phone: check the files
Phones only open your app if your domain says they may. Check that:
https://yourdomain/.well-known/apple-app-site-associationreturns status 200, as JSON, with no redirect, and listsTEAMID.bundle.idwith paths that cover your link;https://yourdomain/.well-known/assetlinks.jsonreturns status 200, as JSON, and lists your package name with the SHA-256 fingerprint of the key that signed the installed app.
The AASA validator and assetlinks.json validator check each file in detail. If you're unsure which Team ID or fingerprint to use, see where to find them.
Testing on an iPhone
Tap from Notes or Messages. Write the link in a note or send it to yourself, then tap it. If the app opens, Universal Links work for that path. Long-pressing the link should offer "Open in [your app]".
Skip Apple's cache while developing. iOS doesn't read your file directly: it gets it through Apple's CDN, which can be hours behind your server. For development builds, add ?mode=developer to each entry in Associated Domains (for example applinks:link.example.com?mode=developer), and turn on Settings → Developer → Associated Domains Development on the phone. The phone then reads your file directly.
See what Apple has. You can fetch Apple's copy of your file from https://app-site-association.cdn-apple.com/a/v1/yourdomain. If it differs from your server's file, Apple hasn't caught up yet.
Watch for the remembered choice. If someone once tapped the domain name in Safari's top bar to stay in the browser, iOS remembers and keeps opening that domain in Safari. Long-press a link and choose "Open in [your app]" to switch it back.
Same-domain links don't count. A link to example.com tapped on a page that's already on example.com stays in Safari. That's by design, and it's a common reason a test from your own website fails.
Testing in the iOS simulator
Universal Links work in the simulator, which is handy for quick checks:
xcrun simctl openurl booted "https://link.example.com/product/42"
The simulator still needs a build with the right Associated Domains entitlement, and it reads the file through Apple's CDN unless you use developer mode as above. Always finish on a real device: the simulator doesn't show in-app browsers or store behaviour.
Testing on Android
Ask Android what it verified. With the app installed and the phone connected:
adb shell pm get-app-links com.example.app
Each domain should show verified. Anything else means Android didn't accept your assetlinks.json for this build. On Android 12 and later you can ask it to check again after fixing the file:
adb shell pm verify-app-links --re-verify com.example.app
Open a link the way a tap would:
adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://link.example.com/product/42"
If the app opens without a chooser, the link is verified for that path.
Check the app's settings. Under the app's Open by default settings, the domain should be listed as verified, and opening supported links should be on.
Use the right build. A build from Android Studio is signed with your debug key, while users get the build Google Play signed. If assetlinks.json lists only one of those fingerprints, the other build won't verify.
Testing inside Instagram, TikTok and other apps
Most links are tapped inside other apps, and those apps often open links in their own browser, which doesn't always hand them to iOS or Android. Test the real paths:
- send the link in an Instagram direct message and tap it;
- put it in a TikTok or Instagram bio and tap it from the profile;
- send it in WhatsApp, Telegram and Slack.
Expect differences: some apps open your app straight away, some show their own browser first. Our Instagram in-app browser post explains what happens and what a link can do about it.
Testing the "not installed" case
Uninstall the app, then tap the link:
- iPhone should go to the App Store, or your chosen page.
- Android should go to Google Play.
- A computer should show a page that makes sense on a desktop.
Then install the app from the store, open it, and check where it lands. If you use deferred deep linking, it should open on the screen the link pointed to, not the home screen. This is the test most teams skip, and the one that tells you whether referrals and campaign links actually work. How deferred deep linking works.
A test matrix worth keeping
| Where the link is tapped | App installed | App not installed |
|---|---|---|
| Notes or Messages (iPhone) | Opens the app on the right screen | App Store, then the right screen after install |
| Messages or Gmail (Android) | Opens the app, no chooser | Google Play, then the right screen after install |
| Instagram direct message | Opens the app, or a page that hands over | Store |
| Opens the app | Store | |
| Desktop browser | Desktop page | Desktop page |
Run it before a release, after changing your domain or signing key, and after updating the association files.
How DL2App helps
DL2App hosts both files on your link domain and checks them on a schedule, the way phones fetch them, with an email if one breaks. Each link's page has a QR code to scan on a real phone, and one-hour test links show what each kind of device would get without changing anything for real visitors. To start, paste your App Store or Google Play link: your first link is live in about a minute. See features and pricing.
Questions people ask
Why does my Universal Link open Safari instead of the app? The most common reasons: the link was typed or pasted into the address bar, it was tapped on a page on the same domain, the user once chose to stay in Safari for that domain, or Apple's CDN still has an older version of your file. Check the file first, then test by tapping from Notes or Messages.
Can I test Universal Links in the iOS simulator?
Yes. Use xcrun simctl openurl booted with your link. The build needs the Associated Domains entitlement, and you should still test on a real device before release.
How do I check if Android verified my App Links?
Run adb shell pm get-app-links with your package name. Each domain should show verified. On Android 12 and later, adb shell pm verify-app-links --re-verify asks it to check again.
Why do my links work in my test build but not for users?
On Android, test builds are usually signed with a different key than the one Google Play uses. Add the app signing key's SHA-256 from Play Console to assetlinks.json. On iOS, check that the release build has the same Associated Domains as your test build.
How do I test deferred deep linking? Uninstall the app, tap the link, install the app from the store, and open it. It should open on the screen the link pointed to.
Start with one link
The free plan has no time limit and needs no card. Create a project, add your app, and send yourself the link.