Debugging Apple App Site Association (AASA) Files Without CDN Caching Delays

Apple's Universal Link CDN Architecture

Starting with iOS 14, Apple ceased querying origin servers directly from end-user devices for Universal Link verification. Instead, when an app declares the Associated Domains capability, Apple's proprietary Content Delivery Network (app-site-association.cdn-apple.com) fetches, parses, and caches the association file on Apple's servers.

While this protects end-user privacy and speeds up app installations, it presents an engineering challenge: changes made to your origin server's apple-app-site-association file can take 24 to 48 hours to propagate through Apple's CDN cache.

Key Origin Server Requirements

Apple's CDN scraper enforces strict HTTP response requirements. Any violation causes the CDN to mark the domain as invalid and cache the failure:

1. HTTPS Only: Valid TLS certificate signed by a recognized certificate authority. Self-signed certificates are rejected.

2. Zero Redirects: The URL https://domain.com/.well-known/apple-app-site-association must return 200 directly. 301, 302, or 307 redirects cause immediate verification failure.

3. Correct Header: The Content-Type header must be application/json. Serving text/plain or octet-stream causes parsing failure.

4. Max Size: The uncompressed JSON payload must not exceed 128 KB.

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": ["TEAMID1234.com.acme.app"],
        "components": [
          { "/": "/offers/*", "comment": "Matches all promotional deep links" },
          { "/": "/invite/*", "comment": "Matches peer invite paths" },
          { "/": "/help/*", "exclude": true, "comment": "Falls back to web documentation" }
        ]
      }
    ]
  }
}

Bypassing Apple CDN During Development

To test AASA updates immediately without waiting for Apple CDN re-indexing, developers can enable developer mode in the app entitlements:

Add '?mode=developer' to the associated domains capability in Xcode:

applinks:go.yourdomain.com?mode=developer

When developer mode is active and the test device has Associated Domains Development enabled in iOS Developer Settings, the device queries your origin server directly on app launch, bypassing Apple's CDN cache entirely.