Apple App Site Association (AASA) File: Hosting and Components

Where the file lives

Create a file named apple-app-site-association, with no extension, and place it so that its address is https://<fully qualified domain>/.well-known/apple-app-site-association. Apple's rule is short: "You must host the file using https:// with a valid certificate and with no redirects."

Apple's debugging note adds the server checks that catch most launches out: a 403 or 404 response means the file is unreachable, the file must be publicly reachable and accept all user agents, and redirects are not supported for it. On gambling sites, geo-blocking and bot protection rules are common causes, so exempt /.well-known/ from both.

Every subdomain is its own site. If the entitlement lists applinks:www.example.com and applinks:help.example.com, both hosts serve a file. The app side of the setup is in the iOS Universal Links setup guide.

The file format

This sample follows the structure of Apple's example, adapted to a sportsbook. ABCDE12345 stands for the Team ID:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.sportsbook"],
        "components": [
          { "/": "/help/responsible-gambling/*", "exclude": true,
            "comment": "Safer gambling pages stay on the web" },
          { "/": "/events/*", "comment": "Event pages open in the app" },
          { "/": "/bet/*", "?": { "market": "?*" } }
        ]
      }
    ]
  },
  "webcredentials": { "apps": ["ABCDE12345.com.example.sportsbook"] }
}

• appIDs lists the apps that may open these URLs, each as <Application Identifier Prefix>.<Bundle Identifier>.
• components is an array of patterns. / matches the path, ? a dictionary of query items, # the fragment, exclude marks URLs the system should not open as universal links, and comment is a note for people reading the file.
• defaults (optional) sets global matching settings, and substitutionVariables (optional) defines named lists that simplify complex patterns.
• webcredentials shares saved passwords between the site and app; appclips lists App Clips. The details dictionary applies only to applinks.

Apple's example lists the exclusion for /help/website/* before the broader /help/* pattern. Keep that order in your own file: specific exclusions first, broad patterns after. Apple's debugging note also asks you to use one format only, either appIDs with components or the older appID with paths, not a mix.

Apple's content delivery network

"Starting with macOS 11 and iOS 14, apps no longer send requests for apple-app-site-association files directly to your web server. Instead, they send these requests to an Apple-managed content delivery network (CDN) dedicated to associated domains." The practical consequences:

• Your server logs show Apple's network, not devices, fetching the file.
• "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."
• A fix to the file is not instant. Plan changes before a campaign, and keep the old patterns working while the new file spreads.

Testing during development

If a staging server is not reachable from the public internet, add an alternate mode to the entitlement: applinks:staging.example.com?mode=developer. Apple's debugging note explains that developer mode bypasses the CDN and fetches the file directly from your domain, which also helps when you change the file often. On a Mac, sudo swcutil dl -d <domain> checks that the file downloads, and sudo swcutil verify checks a URL against a local copy of the file; an excluded path reports a blocked match. Track each step of a release in the implementation checklist.

For a quick format check before deploying, paste the file into the association file linter. How this file differs from Android's is laid out in the side-by-side comparison, and device checks are in the iOS and Android deep link test plan.