Guide · Checked against Apple's docs, October 2026

Universal links not working? A checklist

Links that should open your app open Safari instead, or nothing changes after you edit your file. Work through these in order.

How it works, in three lines

Your website hosts a file called apple-app-site-association that lists your app and the paths it should open.
Your app has the Associated Domains capability, with an entry for each website.
When someone installs your app, iOS downloads the file and checks that the two agree.

1. Is the file where iOS looks, served the way iOS needs?

Apple's documentation is specific: the file is named apple-app-site-association with no extension, it lives in the .well-known folder, and “you must host the file using https:// with a valid certificate and with no redirects.” The address is:

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

Check it from a terminal. You want a 200 and your JSON, not a 301 or 302:

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

Things to look for: a redirect from yourdomain.com to www.yourdomain.com, a login or bot-protection page in front of the file, and a host that serves the file with a certificate that doesn't match.

2. Does every hostname have its own file and its own entry?

Apple's note: if your site uses several hostnames, such as example.com, www.example.com and support.example.com, “each requires its own entry in the Associated Domains Entitlement, and each must serve its own apple-app-site-association file.” A link on www. won't work because the file only exists on the bare domain.

3. Do the IDs and the entitlement match?

In the file, each app is listed as <Application Identifier Prefix>.<Bundle Identifier>, for example ABCDE12345.com.example.app. The prefix is usually your Team ID.
In Xcode, open Signing & Capabilities and add Associated Domains. Add an entry in the form applinks:yourdomain.com.
Use only the hostname in that entry. Apple says not to include path or query components or a trailing slash.
You can write applinks:*.yourdomain.com to match every subdomain. Apple notes the *. prefix works for services other than App Clips.
The apps listed in the file must have a matching Associated Domains entitlement.

4. Does a pattern really match your link?

Each rule in components can match the path ("/"), the query ("?") and the fragment ("#"). A link must match every part a rule specifies. Apple's rules for patterns:

The first match wins. Rules are checked in the order you list them, so put "exclude": true rules before the broader rule they carve out of.
* matches zero or more characters, ? matches exactly one character, and ?* matches one or more.
A part you leave out defaults to *, which matches everything.
Matching is case-sensitive by default. /Puzzle/* won't match /puzzle/paris. Set "caseSensitive": false in defaults if you want it to.

{
  "applinks": {
    "details": [{
      "appIDs": ["ABCDE12345.com.example.app"],
      "components": [
        { "/": "/help/*", "exclude": true },
        { "/": "/puzzle/*" },
        { "/": "/invite/?????" }
      ]
    }]
  }
}

5. Have you given Apple's servers time to catch up?

Since iOS 14 and macOS 11, devices don't fetch your file from your server. They ask an Apple-managed content delivery network, which connects to your server if its copy is old or missing. Apple's guidance:

“Apple's content delivery network requests the apple-app-site-association file for your domain within 24 hours.”
“Devices check for updates approximately once per week after app installation.”
The system also attempts to download the file when a user installs your app.

So a change you made a minute ago may not be on a device yet. For a fresh test, delete the app and install it again after your file is correct.

You can see what Apple's CDN is holding for your domain at the address below. A 404 there means the CDN has no copy of your file yet:

https://app-site-association.cdn-apple.com/a/v1/yourdomain.com

6. Testing on a server only you can reach

If your site is on a private network during development, Apple's CDN can't reach it. Add an alternate mode to the entitlement to bypass the CDN: applinks:yourdomain.com?mode=developer. In developer mode only devices in developer mode can use the domain, and only apps signed with a development profile can use it. Apple also tells you to make sure you don't expose users to security issues such as machine-in-the-middle attacks.

Or let App Pages host the file. Enter your Team ID, bundle ID and paths. App Pages builds the file, serves it with no redirects, and has a tester that tells you whether a link would open your app. It works on every site you make, including your own domain. Make my pages

Sources: Apple's Supporting associated domains, Associated Domains Entitlement, and the applinks reference. This guide isn't legal advice, and Apple's wording can change. Related: The URLs App Store Connect asks for.