AASA validator for iOS Universal Links

What the validator checks

• Where the file is. iOS fetches https://your-domain/.well-known/apple-app-site-association, with no file extension, for each domain listed in your app's Associated Domains.
• Status and redirects. The file must answer 200 directly over HTTPS with a valid certificate. Apple does not follow redirects for it, so a bare domain that redirects to www fails.
• Content. Valid JSON, not an HTML page from a single-page app's catch-all route or a bot check, and no larger than 128 KB uncompressed.
• App IDs. Each entry in appIDs (or appID in the older format) is your 10-character Team ID, a dot, and the bundle ID. JSON keys are case-sensitive, so appId is ignored.
• Paths. components (or the older paths) are read top to bottom and the first match wins, so an exclude rule has to come before the broader rule it carves out of. Enter a full link to see which rule your path hits.
• Apple's copy. Phones don't fetch your file directly; they get it from Apple's CDN at app-site-association.cdn-apple.com/a/v1/your-domain. We compare that copy with yours, because a stale CDN copy explains links that work for you and not for anyone else.

A valid file

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

This opens the app for every path on the domain except /account/…. Writing one by hand? The AASA generator builds it from your Team ID, bundle ID and paths.

Common errors and fixes

• The file returns HTML. Your framework's catch-all route or a CDN challenge answers first. Serve /.well-known/* as static files before any rewrite, and exclude it from bot protection.
• It redirects. Serve the file on the exact host your links use. Each subdomain needs its own copy.
• Works for you, not for others. Apple's CDN still has an older file. It refreshes on its own schedule, often within a day, and can't be purged. During development, add ?mode=developer to the domain in your entitlements so a development build fetches from your server directly.
• The file is fine but the app doesn't open. Check how the link was opened: links typed into Safari's address bar, links to the same domain as the current page, and links inside Instagram or Facebook don't open apps. The Universal Links checklist goes through every cause in order.

Questions people ask

Android next: the assetlinks.json validator.