Making Changes To Your apple-app-site-association File for Universal Links

When you add Universal Links to your app, you have to add a file to your server with the name apple-app-site-association. This is a JSON file that iOS checks so that it knows if it should open a URL in your app instead of in the web browser.

So let's say you already have this set up, and now you want to add a new deeplink into your app. You've added the code to the iOS app and shipped it via the App Store. Now you need to update the apple-app-site-association file on your server, to enable the deeplink into your app.

Updating apple-app-site-association

But iOS doesn't hit your server directly to get that file. It gets scooped up by Apple's CDN, and iOS checks the CDN at a URL like this: https://app-site-association.cdn-apple.com/a/v1/www.neilmacy.co.uk.

The CDN refreshes "within 24 hours" of your update. So after you deploy your change to your apple-app-site-association file, it can take a while for your app to follow the universal link as you'd expect.

It's useful to know that there's a developer mode you can use for testing, which lets you avoid waiting for this cache to update. When you define your associated domain in Xcode, add ?mode=developer and it will skip Apple's CDN and go straight to your server.

<string>applinks:example.com?mode=developer</string>

Updating Devices

Once you've updated your apple-app-site-association file, there's a second delay you need to account for. Devices need to actually check for updates to that file too, and according to Apple's docs:

"Devices check for updates approximately once per week after app installation".

(It's not clear to me if "app installation" means new installs AND app updates, but I assume that's the case. It would be cool if installing an app update triggers an immediate check for an update to the site association file. If you know for sure I'd love to hear from you - email me neil at this domain or get in touch on Mastodon.)

Overriding Universal Links

As a bonus, here's something else I recently learned when I was diving into Universal Links: you can tell iOS NOT to open a link in your app, using the "exclude" property, for example:

{
  "/": "/something-on-web-only",
  "exclude": true
}

Maybe there are some cases where you should open the URL in the app, and some where you want to remain in the browser.

{
  "/": "/profile",
  "comment": "Open /profile links in the app"
},
{
  "/": "*",
  "?": {
    "openOnWeb": "true"
  },
  "exclude": true
}

The code above lets you add an optional query param to a URL, so that you can control when iOS will open it in the browser instead of the app. For example in some parts of your website you might use https://example.com/profile to open the Profile in the app, and in some places you might prefer to keep them on the website, so you'd attach the openOnWeb query parameter like so: https://example.com/profile?openOnWeb.

Further reading

I found both of these articles really useful when learning more about Universal Links.

• Alberto De Bortoli's overview for Just Eat's tech blog is really in-depth, and he links to the Just Eat version of the apple-app-site-association file, which is very informative. They do a lot with Universal Links!
• Apple's docs also have a lot of useful detail on how to configure the apple-app-site-association file.

---

If you liked this article, please consider buying me a coffee to support my writing.