Everything You Need To Know About The Apple App Site Association File

The Apple App Site Association (AASA) file enables iOS features like Universal Links, Shared Web Credentials, Handoff, and App Clips by establishing a secure and verified link between your iOS app(s) and a web domain.

If you've noticed that certain links on the mobile web versions of Instagram or YouTube keep you in the browser, while others redirect you into the app, this behavior is all being driven by the AASA file.

Creating The AASA File

The Apple App Site Association file is a configuration file that defines how URLs are handled and specifies whether they open in a web browser or link directly to content within an app.

Here's a basic example:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.app",
        "paths": [
          "/",
          "/about-us/",
          "/products/*",
          "/services/detail/?id=*",
          "/news/article/*",
          "/promo/*",
          "NOT /private/",
          "NOT /settings/*",
          "*.html"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.app"]
  },
  "appclips": {
    "apps": ["ABCDE12345.com.example.app"]
  }
}

Attempting to visit any of these paths would route the user to the app:

"/",
"/about-us/",
"/products/*",
"/services/detail/?id=*",
"/news/article/*",
...

And for paths prefixed with NOT, the system will not reroute the user, allowing the experience to continue in the browser:

"NOT /private/",
"NOT /settings/*",
...

Deploying The AASA File

When you're ready to deploy your AASA file, you'll need to host it at your website's root or .well-known directory:

• /apple-app-site-association
• /.well-known/apple-app-site-association

Note: there should be no file extension on the AASA file.

For the CDNs to successfully cache this file, it must be hosted on a domain that is available to all IP addresses and ranges, serves the file over HTTPS, does not redirect, and is not blocked by access policies.

You should also make sure your server serves the file with Content-Type: application/json and that the file doesn't exceed 128KB in size.

When you first host your AASA file, Apple’s CDNs are set up to retrieve it within 24 hours, meaning that they will request and cache a copy from your server within the first day of its publication.

This 24 hour window relates only to getting the file into Apple's CDNs for the first time. Subsequent updates happen at a different interval which we'll look at shortly.

Testing & Validation

As your app evolves, you'll need to revise the AASA file to incorporate universal links for new user flows.

Errors in the AASA files are common, so validation of both the behavior and syntax of this file become an essential part of the process. Any mistakes in this file, once acknowledged by Apple's CDNs, can effect universal linking behavior for all users - new or old.

Fortunately, there are several ways of verifying the behavior of the AASA file before the changes make it to Apple.

Bypassing The CDN

Associated Domains support an alternate mode that allows developers to verify the behavior of the modified AASA file by bypassing the CDNs and retrieving the file from your server directly.

To activate this mode in your Xcode project:

1. Go to Signing & Capabilities -> Associated Domains
2. Add ?mode=developer to the end of the domain entry (e.g. applinks:yourdomain.com?mode=developer)

Now, when you build and run your app, it will retrieve the updated AASA file directly from your server.

You can only use alternate modes during development and you must remove the query string from the Associated Domains before you submit your app to the App Store.

Verifying AASA File Configuration

You can use the following tool to verify the syntax and configuration of your AASA file:

If I need to update the AASA file at work, I'll start by making changes to the version in our staging environment, then use the links above to validate the configuration, and will then enable developer mode for local testing.

After confirming everything works as expected, I'll bring those modifications over to the production environment. But now, the question is, how long will it take for all clients to receive the updated version of this file?

Rolling Out Changes

You can check if Apple's CDNs have picked up the latest version of the file by visiting:

• https://app-site-association.cdn-apple.com/a/v1/{YOUR_DOMAIN_HERE}
• https://app-site-association.cdn-apple.com/a/v1/facebook.com

If the CDN does in fact have the most recent version of the file, then any new app installations will also receive this latest version. For existing users, however, their devices will only check for an updated copy once per week.

Reinstalls of the app will fetch the latest version from the CDN.

In effect, the rollout period for any change to the AASA file is both the time it takes for the CDN to refresh its cache combined with this week long check-in period for existing users.

Still seeing the old version?

While you can't clear the CDNs cache, you can at least verify that the AASA file will be correct when the cached version does update.

Adding any query parameter to the link above will force the CDNs to re-request the resource, so you'll be able to verify that the future version of the file will be correct once the cache updates.

https://app-site-association.cdn-apple.com/a/v1/<domain>?digitalbunker

When will it update?

To better understand the remaining time before the cached version is updated, we can look at the Cache-Control field in the response headers from the CDN.

The Cache-Control header is used by web servers to dictate how, and for how long, both browser and intermediary caches (like CDNs) should cache the provided version of a file.

Let's use Facebook and Yelp as examples:

• https://app-site-association.cdn-apple.com/a/v1/facebook.com
• https://app-site-association.cdn-apple.com/a/v1/yelp.com

Now, we can determine when the cache will update by subtracting age from max-age:

In playing around with this approach, it seems like the refresh rates are fairly variable with the shortest max-age being 3,600 seconds, or 1 hour, and the longest being 21,600 seconds, or 6 hours.

It also may be useful to know that Apple's CDNs override the Cache-Control settings specified by the original website. For example, accessing the AASA file from Yelp directly has a max-age: 1200, but when retrieving it from Apple's CDNs, it's max-age: 3600.

By caching the file longer, Apple is able to minimize the frequency of requests to the original servers, reducing traffic, and load on both their network and the origin server.

Hope you enjoyed this article! If you did, please consider sharing 😊🙏.

If you're interested in more articles about iOS Development & Swift, check out my YouTube channel or follow me on Twitter.

And, if you're an indie iOS developer, make sure to check out my newsletter! Each issue features a new indie developer, so feel free to submit your iOS apps.