Apple App Site Association (AASA) explained

Introduction

The Apple App Site Association (AASA) file is a small, server-hosted JSON document that lets iOS know when to open a link in your app instead of in Safari. It underpins features like universal links and some app/web integrations.

What is the Apple App Site Association?

The AASA file tells Apple which domains are linked to your iOS app. When an iPhone or iPad taps a link to your domain that matches the AASA, iOS can launch your app and navigate to the right screen.

Why AASA matters

• Universal links provide a seamless user experience: a web link can open your app directly.
• You can declare multiple domains and multiple app IDs.
• The file also supports related features like web credentials (for iCloud Keychain) and activity continuation.

Where to host the AASA file

Two common locations:

• https://your-domain.com/apple-app-site-association
• https://your-domain.com/.well-known/apple-app-site-association

The file must be served over HTTPS, without redirects, and with the correct content type (JSON). It should not have a file extension.

Inside the AASA file: a simple example

Below is a minimal, valid example you can adapt. Replace <TEAMID> and <BUNDLEID> with your values.

{
  "applinks": {
    "details": [
      {
        "appID": "<TEAM_ID>.<BUNDLE_ID>",
        "paths": ["/", "/shop/*", "/products/*"]
      }
    ]
  },
  "webcredentials": {
    "apps": ["<TEAM_ID>.<BUNDLE_ID>"]
  }
}

Notes:

• "paths" specify which URL paths trigger the app. You can use wildcards like * to cover groups of pages.
• The "apps" array in webcredentials is optional and relates to iCloud Keychain login flows.

Testing and troubleshooting

• After publishing, try tapping a matching URL on a device to see if the app opens.
• Check that the AASA file is reachable at the exact location and served with JSON content type.
• If the app doesn’t open, confirm your Team ID and Bundle ID are correct, and verify there are no redirects or compression that alters the file.

Best practices and quick tips

• Keep the AASA file small and forward-compatible; add paths as you ship features.
• Use specific paths rather than broad patterns to avoid unintended openings.
• Use HTTPS-only hosting and avoid caching issues during updates.

Next steps

• Gather your Team ID and iOS Bundle ID from your App ID configuration.
• Add the associated domains in Xcode (Capabilities > Associated Domains) and upload the AASA file to your site.
• Test across devices and monitor app-opening behavior after link taps.