Apple App Site Association (AASA)

Definition

The apple-app-site-association file is a JSON document hosted at a domain's /.well-known/ path that tells iOS which app is allowed to handle which URLs on that domain.

It is the iOS half of the domain-to-app handshake behind Universal Links — Android's equivalent is assetlinks.json. Apple fetches the file when your app is installed, caches the result, and from then on decides every link tap against that cached copy. Nothing about a Universal Link works until this file is present, correctly shaped, and served under a specific and unforgiving set of rules.

What the file looks like

This is a complete, current AASA file. It has no file extension — not .json — and it is not signed. Signing was dropped in iOS 9.3; if you find a guide telling you to run openssl smime, it predates that change by a decade.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.shop"],
        "components": [
          {
            "/": "/products/*",
            "comment": "Open product pages in the app"
          },
          {
            "/": "/orders/*",
            "?": { "guest": "true" },
            "exclude": true,
            "comment": "Guest order lookup stays on the web"
          },
          {
            "/": "/help/*",
            "exclude": true,
            "comment": "Support content stays on the web"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.shop"]
  },
  "appclips": {
    "apps": ["ABCDE12345.com.example.shop.Clip"]
  }
}

ABCDE12345.com.example.shop is an App ID: the App ID Prefix, a dot, then the bundle identifier. The prefix is usually your Team ID but is not guaranteed to be — App IDs created before Team ID unification, or migrated between accounts, keep their original prefix. Copy it from the Identifiers list in your Apple Developer account rather than assuming.

appIDs and components vs. the legacy format

There are two AASA formats in the wild, and the older one still works — which is why so much copy-pasted config is a decade out of date. The modern format replaced appID/paths with appIDs/components in iOS 13, and the difference is not cosmetic: paths could only match on the path, while components can match query parameters and fragments too.

You can ship both keys in one file. iOS 13 and later read components and ignore paths; iOS 12 does the reverse. Wildcards are the same in both: * matches any number of characters including /, and ? matches exactly one character.

The hosting rules, and why each one bites

Apple does not fetch this file from your server directly. A CDN operated by Apple fetches it, and your device asks the CDN. That indirection is the source of most AASA problems, because the CDN is strict in ways a browser is not — it will not follow a redirect, and it will not tell you why it gave up.

Check what the CDN actually holds rather than what your server returns. This is the copy your users' devices are given:

# What Apple's CDN is serving to devices right now
curl -sS https://app-site-association.cdn-apple.com/a/v1/example.com

# What your origin returns — -I for headers, -L to expose any redirect
curl -sSIL https://example.com/.well-known/apple-app-site-association

# On macOS: force a fetch and print why it failed
swcutil dl -d example.com

Caching, and why your change hasn't taken effect

There are two caches between your edit and a working link, and they expire on different schedules. Apple's CDN refreshes its copy of your file periodically — allow up to 24 hours. Separately, each device caches the association it was given, and re-fetches on app install, on app update, and occasionally in the background. Editing the file does not push anything to installed devices.

For development, add ?mode=developer to the entitlement. That bypasses the CDN entirely and makes the device fetch straight from your domain, so edits take effect immediately — after enabling Settings → Developer → Associated Domains Development on the device.

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:example.com</string>
  <string>applinks:www.example.com</string>
  <string>webcredentials:example.com</string>

  <!-- Development builds only: bypasses Apple's CDN, no propagation delay.
       Must be removed before submitting to the App Store. -->
  <string>applinks:staging.example.com?mode=developer</string>
</array>

Getting it right the first time

Most AASA files are wrong in one of five ways, and all five are mechanical: the App ID Prefix is the Team ID when it shouldn't be, the file has a .json extension, components is nested one level too deep, a broad wildcard shadows the exclusions below it, or the file is valid but sitting behind a redirect. None of them produce an error message — the link simply opens Safari.

1. Copy the App ID from the Identifiers list in your Apple Developer account, prefix included.
2. Write the exclusions above the broad matches in components.
3. Deploy, then curl -sSIL the URL and confirm a single 200 with Content-Type: application/json and no redirect in the chain.
4. Wait for Apple's CDN, or use ?mode=developer on a dev build to skip the wait.
5. Delete and reinstall the app — association is fetched at install, so an already-installed build keeps the old answer.