Deep Link Doctor
Home / Developer notes

AASA changes are not picked up on devices

Edited your AASA file but iOS still uses the old rules? How Apple's CDN caches the file, how often devices check, and how to test changes with developer mode.

SymptomYou edited the AASA file but devices still follow the old rules.
Likely causeApple's CDN caches the file and devices only check for updates roughly once a week after install.
FixWait for the CDN to refetch, reinstall the app on test devices, and use developer mode while iterating.

Short answer: iOS devices fetch the apple-app-site-association file from Apple's CDN, not your server. Apple says the CDN requests your file within 24 hours and devices check for updates about once a week after install. There is no way to invalidate the CDN, so reinstall the app on test devices and use ?mode=developer while iterating.

What is happening

Apple's associated domains CDN: an Apple-managed cache that, since iOS 14 and macOS 11, fetches your apple-app-site-association file and serves it to devices in place of your web server.

Apple documents three timings that explain stale rules:

  • "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."
  • "When your app is installed, devices download the file from the CDN immediately ... There is no direct CDN invalidation option."

So a change can take a day to reach the CDN and up to a week more to reach an installed app.

Why does this happen?

The cache protects your server and makes link handling fast, but it means edits are not instant. Most "my fix did not work" reports are really the old file still in use.

  • CDN not refreshed yet: the edit was made in the last 24 hours.
  • Device not refreshed: the app was installed before the change and the weekly check has not run.
  • CDN cannot fetch: a redirect or block means the CDN keeps an old copy or none. See AASA redirect or blocked.

How to confirm it

  1. Compare your live file with curl -s https://example.com/.well-known/apple-app-site-association.
  2. Compare with the CDN copy: curl -i https://app-site-association.cdn-apple.com/a/v1/example.com. Check the Cache-Control header and whether the body matches. This URL is widely used but not documented by Apple.
  3. On a test device, capture a sysdiagnose and open swcutil_show.txt. Read Last Checked and Next Check for your domain.

How to fix it

  1. Wait up to 24 hours for the CDN to refetch, then check the CDN copy again.
  2. Delete and reinstall the app on test devices, which downloads the current CDN copy immediately.
  3. While testing, add an alternate mode to the entitlement: applinks:example.com?mode=developer. Apple says this bypasses the CDN and "pulls your AASA directly from your domain".
  4. Turn on Settings > Developer > Universal Links > Associated Domains Development on the device. Developer mode needs a development-signed app, and the file must be in /.well-known/.
  5. Remove ?mode=developer before shipping, since it only works on opted-in devices.
Associated Domains entitlement while testing:
applinks:example.com?mode=developer
applinks:www.example.com?mode=developer

Check the file before each deploy with curl -I https://example.com/.well-known/apple-app-site-association and sudo swcutil verify on a Mac, so you are not waiting a day to discover a typo. The universal links setup guide lists the device steps.

FAQ

Common questions

Can I force Apple's CDN to refresh?

No. Apple says there is no direct CDN invalidation option. The CDN refetches on its own schedule, documented as within 24 hours.

Will users get my fix without updating the app?

Yes, eventually. Devices check for a new file roughly once a week after installation, so most users pick up the change within about a week of the CDN refreshing.

Does developer mode work on the App Store build?

No. Apple says developer mode only applies to apps signed with a development profile on devices where the user has opted in. Production users always go through the CDN.

How do I test on a Mac?

Run `swcutil developer-mode -e true` to enable developer mode for associated domains on macOS. You can then test file changes with `sudo swcutil verify` against a local copy before deploying.

What are UTM parameters?

UTM parameters are tags added to the end of a link, such as utm_source and utm_campaign, that tell analytics tools where a visit came from. They let you see which campaign, channel and ad brought each visitor.

Which UTM parameters are required?

Use utm_source, utm_medium and utm_campaign on every campaign link. utm_term and utm_content are optional and help you compare keywords or ad variants.