Skip to main content

Why Your Link Opens the Store or the Browser Instead of the App

You tap a link that should open your app. The browser opens instead, or a store page appears although the app is already on the phone. In each case the system did not hand the link to your app.

This guide is organised by symptom, with the check to run for each. The file formats are in the AASA file guide for iOS and the assetlinks.json guide for Android.

How iOS and Android decide whether a link may open an app

Both platforms use the same idea: the app names the domain, and the domain serves a file that names the app.

  • iOS, Universal Links. The app carries the Associated Domains entitlement (a capability added in Xcode) with an applinks: entry, and the domain serves an apple-app-site-association (AASA) file. The system checks the file when the app is installed. Since iOS 14 the device gets it from a content delivery network (CDN) that Apple runs, not from your server, and looks for updates about once a week.
  • Android, App Links. The manifest has an intent filter (a declaration of the URLs an activity accepts) marked android:autoVerify="true", and the domain serves assetlinks.json with the app's package name and the SHA-256 fingerprint of its signing certificate. Android verifies each host when the app is installed.

The device decides, from a check that ran before the tap. When the association holds, the system hands the URL to the app without going through the browser. When it does not, the URL loads in the browser, and what happens next, including a redirect to a store, is the web server's doing.

Symptom: the link always opens the browser

On iOS, first confirm that the association verified. (Android has its own section below.) Apple's technote Debugging universal links gives these checks:

  1. The entitlement. It must hold applinks: followed by the fully qualified domain, with no port number. Each subdomain needs its own entry and its own file. A wildcard entry such as applinks:*.example.com is matched against the file on the root domain.
  2. The HTTP response. Run curl -v https://links.example.com/.well-known/apple-app-site-association. A 301 or 302 fails: redirects are not supported. A 403 or 404 means the site denied access. The file has to be served over HTTPS with a valid certificate, to every IP address and every user agent.
  3. The content. Use the current format (appIDs with components) or the legacy one (appID with paths), never a mix.
  4. The cache. A device downloads the file from Apple's CDN when the app is installed, and Apple offers no way to invalidate the CDN's copy. To pick up a new file, reinstall the app.

Symptom: it works from Notes but not from the address bar or the same site

This is by design. Apple states that entering a URL in the browser's address bar never opens the app, because that is direct navigation inside the browser. Apple's test is to paste the link into Notes and long-press it: when the association is valid, the menu offers both your app and the browser.

When someone is browsing your site in Safari and taps a universal link on the same domain, Safari keeps them in the browser. A login button on example.com that points at example.com/login will not open the app, even when the AASA file covers /login. Apple's fix is a different subdomain: add it to the entitlement, serve an AASA file from it, and point the button at it.

Third-party browsers on iOS decide for themselves whether to support universal links. And a link that is not a universal link but redirects to one goes through the browser on its way to the app.

Symptom: it used to work and stopped on one device

Check the phone before the server. On iOS, the choice made in the long-press menu becomes that device's default for the domain. Choose the browser once and later links from that domain open there, until you long-press a link and choose the app.

On Android, the "Open by default" settings screen lets the user choose which links an app opens, and that choice takes precedence over verification. Only one app at a time can be associated with a domain. If two of your apps resolve the same host and path, such as a lite and a full version, only the one installed most recently receives the links. Check the state for the current user:

adb shell pm get-app-links --user cur com.example.myapp

A changed assetlinks.json also arrives late. Android 15 and later re-verify in the background, and a change can take up to seven days to reach every device. Android 14 and earlier typically pick it up only when the app is installed or updated.

Symptom: Android shows a chooser, or opens the browser

From Android 12, a web link opens an app only when the app is approved for that domain, and otherwise goes to the default browser. On earlier versions, an unverified link might show the disambiguation dialog (the app chooser). The cause is the same: the domain is not verified for the installed build.

Install the app, wait at least 20 seconds for verification to run, then ask the system (Android 12 and later):

adb shell pm get-app-links com.example.myapp

Expect verified next to the host. none means nothing has been recorded yet, so wait and run it again. Then go through the causes in Google's App Links guides, starting with the troubleshooting page:

  • Fingerprint. The file must list the fingerprint of the certificate that signed the installed build, in upper case. With Play App Signing that is the key Google signs your releases with, shown in Play Console. A debug build needs its debug certificate listed too.
  • Manifest. The filter needs android:autoVerify="true", the BROWSABLE category and the https scheme.
  • Redirects. A redirect from http to https, or from the bare domain to www, makes verification fail.
  • Other hosts. On Android 11 and earlier, one host that fails verification stops the app from becoming the default handler for all of them.
  • Dynamic rules. On Android 15 and later, an exclusion rule in assetlinks.json keeps matching URLs out of the app.

App Links also need a device with Google services installed.

Symptom: it fails inside another app's built-in browser

On Android, a link tapped in a WebView (the embedded browser component) is by default handed to the system, which launches an app that handles the URL, usually the default browser. The host app can override that and load links inside its own WebView, so whether your App Link reaches the system is its choice.

On iOS, Apple says universal links open your app from links tapped in a browser app and in WKWebView, the embedded web view. The host app still controls its web view: its navigation delegate can accept or reject navigations. Apple's pages do not say how each app treats your link.

Test inside the apps your audience uses, on real devices, and again after those apps update: behaviour differs from app to app.

Symptom: the app is installed but the link goes to the store

Apple and Google document where a link goes when no app is approved for it: the browser, or possibly the chooser before Android 12. Neither documents a store. A link handed to the app goes there directly, without the browser or your website. So when the store appears, the web server received the request and answered as it does for a visitor without the app.

The checks are those in the sections above. Rule out two cases first. One is a debug build whose certificate is missing from assetlinks.json: it does not verify, even when the store build does. The other is a tap the system does not hand over: from the iOS address bar, a page on the same domain, or an in-app browser that keeps links to itself.

On Android, Chrome also accepts intent: URLs that name a package and a fallback URL: it opens the app when the intent resolves and loads the fallback when it does not. Chrome will not launch an app this way without a user gesture, or after a redirect from a typed-in URL.

The tools Apple and Google give you to check

ToolPlatformWhat it tells you
Settings, Developer, Universal Links, DiagnosticsiOS, with Developer Mode and Associated Domains Development onWhether a URL is valid for an installed app
sudo swcutil dl and sudo swcutil verifymacOSWhether the AASA file downloads and matches a URL
swcutil_show.txt in a sysdiagnoseiOSThe user's choice and whether the file was approved
adb shell pm get-app-links and pm verify-app-links --re-verifyAndroid 12 and laterThe verification state of each host, and a fresh verification run
adb shell am start --debug-linkAndroid 17 and laterWhich apps, manifest filters and dynamic rules matched a URL
Play Console Deep links page, Android Studio App Links AssistantAndroidYour links and their configuration errors

Doing this with AdTo

AdTo is a hosted link service. Your links live at https://<username>.adto.app/<slug>, and AdTo generates both association files for that host from the app record in the dashboard, with nothing to upload. The AASA file needs the app's bundle ID and Team ID, and assetlinks.json its package name and fingerprints. A Verify button next to each file fetches what AdTo serves for the account and warns when a package has no saved fingerprints; such a package never verifies.

In the app, add applinks:<username>.adto.app to the entitlement and the same host to an autoVerify intent filter, as Platform setup describes. Use the explicit host: a wildcard entitlement never verifies, because the parent domain serves no association file. With the Flutter SDK, flutter_adto, call FlutterAdto().diagnostics() from a debug build. It reports a bundle ID or package that differs from the app record and, on Android 12 and newer, each link host the system has not verified.

When the system does not hand a tap to the app, the request reaches AdTo. On Android, a Chrome-family browser gets an intent:// redirect that opens the installed app and falls back to the store, provided the app record has a scheme and a package. Android in-app browsers get a plain redirect to the destination. The Facebook and Instagram ones are the exception: with a scheme and a package saved, a page tries the app first and then continues to the destination. On iOS, AdTo never tries a custom scheme (a URL such as myapp://) automatically; a saved scheme is offered as an "Open in app" button on AdTo's own pages.

Create an AdTo account to try it. The full decision order is in How a tap is routed, and more symptoms are in the troubleshooting guide.