When links open the App Store instead of your app

The app is installed, the link points at your own domain, and iOS still shows the store listing. That is iOS telling you it could not verify the link, in the only way it has of telling you anything.

5 August 2026 by PAD team

First, make sure it is this problem

Two complaints get written the same way in search and have opposite causes.

If yours is the blank page, this article is the wrong one: that is the WebView problem. What follows deals with the first row.

How iOS decides

When a link to your domain is tapped, iOS looks for a file that grants your app permission to handle URLs on that domain. It fetches it once, caches the result, and either opens the app or gives up and treats the URL as an ordinary web address.

https://yourdomain.com/.well-known/apple-app-site-association

There is no error surface. A malformed file, a redirect, an expired certificate, all produce the same outcome: the app does not open, and you are left guessing which of them it was.

The checklist, in the order things actually break

1. The file is served wrong

More than half of broken setups are here. The file must be reachable over HTTPS with a valid certificate, with no redirect at all, and no .json extension even though the content is JSON.

curl -sI https://yourdomain.com/.well-known/apple-app-site-association

HTTP/2 200                       ← not 301, not 302
content-type: application/json   ← not text/html

A redirect from www to the apex, or from HTTP to HTTPS, counts as a redirect and fails. Serve the file at both hostnames if you use both.

2. The identifiers are wrong

appID is the team identifier and the bundle identifier joined by a dot. Getting this wrong is easy because the team ID is not the one you see most often in Xcode.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/app/*", "comment": "app deep links" }
        ]
      }
    ]
  }
}

3. The path pattern does not match

A components entry of /app/* matches /app/thing and does not match /thing. Wildcards are literal, and the pattern is checked against the path only, not the query string.

4. The entitlement is missing on the app side

The app needs an Associated Domains entitlement listing applinks:yourdomain.com, and it has to be present in the build that is actually installed. A file that is correct on the server does nothing if the app was shipped without the entitlement.

5. iOS cached the failure

The result is cached, so a fix does not take effect on a device that already failed. Reinstalling the app forces a fresh fetch. This is the reason for a lot of "it works on my colleague's phone" confusion.

The cases where iOS refuses on purpose

Some failures are not failures. Knowing them saves you from debugging a system that is behaving exactly as designed.

• A URL typed into Safari's address bar never opens the app. Apple treats a directly entered address as a request for the web page.
• A link that points at the same domain as the page you are on stays in the browser. Universal links do not fire within their own site.
• Once the visitor taps the breadcrumb at the top right of your site inside Safari, iOS remembers that preference and stops opening the app until they choose otherwise.
• Inside most in-app browsers, universal links are unreliable by design. Facebook and Instagram intercept navigation before iOS gets a say.

That last one is where the two problems in this article meet. In a WebView, a universal link may fail and the store fallback may also fail, and the visitor gets nothing at all.

Verifying without guessing

Apple's validator tells you whether the file parses and is served correctly, which covers the first three items on the checklist:

https://search.developer.apple.com/appsearch-validation-tool/

On a real device, install a build with the entitlement, then send yourself the link in Messages and tap it there. Messages honours universal links, Safari's address bar does not, and testing in the wrong place produces a false failure that sends people rewriting a file that was already correct.