I'm sure it's happened to you more than once: you spend ages configuring your app's links, and just when you think everything's ready, your phone decides to ignore the app and open the web browser . It's a frustrating situation that makes you think the code is wrong, but the reality is that both iOS and Android have their own quirks and rules that aren't always obvious at first glance.
To avoid going crazy by randomly editing files, it's essential to understand that we're dealing with a complex interaction between servers, signing certificates, and the operating system. Whether you're struggling with Apple's Universal Links or Google's App Links, the smartest approach is to use a process of elimination to pinpoint the exact problem.
The Universal Links Labyrinth on iOS

Before you panic, check if the link is actually broken. Apple has designed its links so that, in certain scenarios, the browser retains control . For example, if the user manually types the URL into Safari or if the link points to the same domain where the app is already located, the app won't launch. To test this, the easiest way is to paste the link into the Notes app and hold it down; if the menu suggests opening your app, the configuration is correct and this is simply the expected system behavior.
A critical point is that, since iOS 14, devices don't query your server directly, but instead go through Apple's CDN . This means you can have a perfect apple-app-site-association file, but if Apple hasn't indexed it, the phone won't know. To diagnose this, there are tools like Appy's validator or the swcutil utility on Mac to compare the URL with the local file.
If you have Developer Mode enabled on your iPhone, you can go to Settings > Developer > Universal Links to view the diagnostics panel. There you'll see if the status is approved or denied . Keep in mind that the system checks the association approximately every week, although reinstalling the app usually forces an immediate update of the AASA file.
Mastering App Links on Android
On Android, the situation is different because there are no intermediaries; the device downloads the assetlinks.json file directly from the .well-known folder. Starting with Android 12, verification is much stricter : if the link isn't verified, the system won't even ask the user and will open the default browser.
One of the most common and frustrating errors occurs with app signing. It often works in testing but fails in production because, when using Play App Signing, Google signs the app with a different key than the one used for uploading. To fix this, you need to copy the SHA-256 fingerprint from the Google Play console (in Release > Setup > App signing) and add it to the JSON file, also keeping the debug fingerprint to avoid disrupting the workflow.
If you're stuck and everything seems fine, the problem might be the system cache . Clearing the storage and cache of Android System Webview, Google Play Services, and Google Services Framework, followed by a reboot, has saved many developers from persistent redirect errors.
What's New in Android 15 and Dynamic App Links

Android 15 introduced Dynamic App Links, a fantastic feature that allows you to change app opening rules from the server without requiring the user to update the app. This is done through the `dynamic_app_link_components` section in `assetlinks.json`, which is invaluable for temporary marketing campaigns.
However, there's a golden rule: the JSON file cannot expand the scope defined in the manifest. Ideally, you should configure a very broad intent filter in the manifest and then use the JSON to refine and restrict exactly which URLs should trigger the application.
Technical considerations and common failures
It's vital to remember that if a link isn't a standard anchor tag, but is instead triggered by JavaScript or a new WebView, the operating system won't recognize it as a user-initiated action and won't open the app. It's always recommended to use traditional links.
Be careful with redirects as well. If your server redirects from http to https or from example.com to www.example.com, Android might fail the verification. The assetlinks.json file must be directly accessible without any intermediate steps. On the other hand, while JavaScript redirects fail, HTTP 3xx redirects usually preserve the reference to the original event, allowing the link to function correctly.
To verify the configuration on Android, simply open your browser and navigate to your .well-known/assetlinks.json file. Check that the package name and SHA-256 fingerprint exactly match what you configured in the Play Console. Consistency between certificates, proper file publication, and understanding of operating systems ensure a seamless experience for the end user, preventing the browser from becoming an obstacle.
Table of Contents