skip to content

In an apple-app-site-association file, how do the applinks components decide which URLs open the iOS app, including exclusions and match order?

level: middleimportance: should knowfreq 35%

answer

  1. details: which apps, which patterns
  2. path, query and fragment keys
  3. an exclude flag on a pattern
  4. the first pattern that matches wins
  5. wildcards: star, question mark, ?*

basics

~20 s

Each applinks details entry names apps by team-prefixed ID and lists components patterns over path, query and fragment. iOS walks the patterns in order and the first match wins; exclude: true keeps that URL on the website.

solid answer

~40 s

In the `applinks` section, each `details` entry pairs `appIDs` (team prefix plus bundle ID) with a `components` array. Each component can constrain the path (`"/"`), the query (`"?"`, a string or a dictionary of query-item names to value patterns) and the fragment (`"#"`), and a URL matches only when it satisfies every key the component sets. Patterns accept `*` (zero or more characters), `?` (exactly one) and `?*` (at least one). Order is the key rule: iOS checks the array top to bottom and the first match wins, so an `"exclude": true` entry must sit above the broader pattern it carves out. `caseSensitive` and `percentEncoded` can be set per component or as `defaults`, the more specific level winning. The file itself lives at `/.well-known/apple-app-site-association` over HTTPS with no redirects, fetched through Apple's CDN.

code

json · 19 lines
json
{
  "applinks": {
    "details": [
      {
        "appIDs": [ "ABCDE12345.com.example.zoo" ],
        "components": [
          { "#": "no_universal_links", "exclude": true,
            "comment": "Any page can opt a link out with this fragment" },
          { "/": "/animals/*/print", "exclude": true,
            "comment": "Printable fact sheets stay on the website" },
          { "/": "/animals/*",
            "comment": "Animal pages open in the app" },
          { "/": "/tickets/*", "?": { "order": "?*" },
            "comment": "Ticket pages open in the app only with an order number" }
        ]
      }
    ]
  }
}

go deeper

for a junior

Recall where the file lives, /.well-known/apple-app-site-association over HTTPS, and that appIDs are team prefix plus bundle ID.

for a middle

Explain components matching: path, query and fragment keys, the three wildcards, a match needing every specified key, and exclude.

for a senior

Show that order decides because the first match wins, and trace a real URL list through a file, including query-dictionary patterns and case rules.

for a principal

Treat the file as a contract between web and app teams: who may edit it, how pattern changes are reviewed, and that devices pick changes up over days.

## What the file is The **`apple-app-site-association`** file (AASA) is the website half of a universal link. It is a JSON file with no extension, served at `https://<host>/.well-known/apple-app-site-association`, and its `applinks` section tells iOS which apps may open which of the site's URLs. The app half is the `applinks:<host>` entry in the Associated Domains entitlement. The same file can also carry `webcredentials` and `appclips` sections for other services; the `details` structure below applies only to `applinks`. ## The structure of applinks - **`details`**: an array; each entry is one group of apps and the URLs they handle. - **`appIDs`** (or the single `appID`): each value is `<Application Identifier Prefix>.<Bundle Identifier>`, for example `ABCDE12345.com.example.zoo`. The prefix is part of the format, so a bare bundle ID is wrong. - **`components`**: an array of pattern dictionaries, available since iOS 13. - **`defaults`**: default pattern settings, either for one `details` entry (app level) or for the whole `applinks` object (domain level, since iOS 14). ## How one component matches a URL A component dictionary may contain these keys: | Key | Matches | Example | |---|---|---| | `"/"` | the URL's path | `"/animals/*"` | | `"?"` | the query, as a string or as a dictionary of query-item name to value pattern | `{ "order": "?*" }` | | `"#"` | the fragment | `"no_universal_links"` | | `exclude` | when `true`, a match means *do not* open the app | `true` | | `caseSensitive`, `percentEncoded` | how the patterns compare | `false` | | `comment` | nothing; notes for humans | | The wildcards are `*`, which matches zero or more characters greedily, `?`, which matches exactly one character, and `?*`, which matches at least one. A URL matches a component only when it matches **every** key that component specifies. Apple's own example `{ "/": "abc", "?": "def", "#": "*" }` matches `https://www.example.com/abc?def` but neither `/abc` alone nor `?def` alone. A component that names only a path, like Apple's `"/buy/*"` example, matches any URL whose path starts that way. ## Order and exclusions The order of the `components` array is the order iOS follows when looking for a match, and **the first match wins**. Two consequences: 1. An exclusion must come **before** the broader pattern it carves out. Placed after `"/animals/*"`, an exclude for `"/animals/*/print"` is never reached, because the broader entry has already matched. 2. Because the first match decides, one domain can hand some URLs to one app and leave the rest to another, or to the website. Apple describes exactly this: designate one app for specified URLs and another for the rest, by giving each app its own `details` entry with its own `appIDs` and `components`. ## Defaults at three levels You can set `caseSensitive` and `percentEncoded` at the domain level (`applinks.defaults`), the app level (the `defaults` of a `details` entry) and the URL level (inside a component). The more specific level overrides the less specific. Apple's `details` example sets `"defaults": { "caseSensitive": false }` so its patterns ignore case. ## The zoo file worked through With the file shown in the code example, iOS decides: - `/animals/red-panda`: the fragment rule needs `#no_universal_links`, the print rule needs `/print`, so the third entry matches and the **app** opens. - `/animals/red-panda/print`: the second entry matches first and excludes it, so the **website** opens. - `/animals/red-panda#no_universal_links`: the first entry excludes it. - `/tickets/confirm?order=8841`: the fourth entry matches, so the **app** opens. - `/tickets/confirm` with no query, or `/visit/hours`: nothing matches, so the website handles them. ## Where the file is served and how changes travel - Host it over `https://` with a valid certificate and **no redirects**. - Each subdomain needs its own entitlement entry (or a `*.` wildcard entry) and serves its own file; the apex domain's file does not cover `www`. - Since iOS 14, devices ask an Apple-managed CDN for the file instead of your server. Apple says the CDN requests your file within 24 hours and devices check for updates roughly once a week after the app is installed, so an edited pattern does not reach phones at once. - A development server that the public internet can't reach can be used with an alternate mode, `applinks:<host>?mode=developer`, which bypasses the CDN for development-signed builds on devices that have opted in.

  • The zoo team fixed a pattern in its apple-app-site-association file this morning; why do testers' phones still behave the old way?
    Since iOS 14, devices fetch the file through Apple's associated-domains CDN, not from your server. Apple says the CDN requests the file within 24 hours and devices check for updates about once a week after installing the app, so a change propagates slowly. For development against a private server, `?mode=developer` in the entitlement bypasses the CDN on opted-in devices.
  • How can one domain send its /shop/ pages to a shopping app and everything else under /animals/ to the zoo app?
    Give `applinks` two `details` entries, one per app ID, each with its own `components`. Because iOS takes the first matching pattern, put the narrower patterns where they will be checked first and add `exclude` entries for paths that should stay on the website.

  • The most specific pattern wins, wherever it sits in the components array.
  • An exclude entry applies even when it is listed after the broad pattern.
  • appIDs take the bare bundle ID, without the team prefix.
  • The file needs a .json extension and may redirect to a CDN copy.
  • One file on the apex domain also covers www and every subdomain.