What Is An AASA (apple-app-site-association) File?

Picture this: you want to get started with Universal Links on iOS and the documentation at Apple has asked you to create and host an AASA file. So, what is an AASA file?

The AASA (short for apple-app-site-association) is a file that lives on your website and associates your website domain with your native app. In other words, it’s a safe way to prove domain ownership to iOS. With URI schemes, which were the standard way for opening apps on iOS until iOS 9, app developers could register any URI scheme of their liking and iOS, without any verification, would respond to those URI schemes by opening apps. For example, if an indie developer registers the fb:// URI scheme for a test app, there was nothing to stop that, even thoughfb:// is used by the Facebook native app. The AASA file makes Universal Links unique and secure because there is no way for an indie developer to host an AASA file on the facebook.com domain.

Let’s look at some basics of the apple-app-site-association file that will help you in building and hosting one on your domain.

The AASA file contains a JSON object with a list of apps and the URL paths on the domain that should be included or excluded as Universal Links. Here is a sample AASA file:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "3XXXXX9M83.io.branch-labs.Branchster",
        "paths": [ "NOT /e/*", "*", "/", “/archives/201?/* ]
      }
    ]
  }
}

In the AASA JSON, each app specific domain contains a dictionary of appID and paths. Let’s look at what each key in the AASA JSON object is:

• applinks: Since the AASA file can also serve other purposes (for example, Shared Web Credentials), the applinks object defines the section of the file used by Universal Links.
• apps: The apps array must be present, but will always be empty.
• appID: Built by combining your app’s Team ID* (or the Apple App Prefix) and the Bundle Identifier**. In the example above, 3XXXXX9M83 is the Team ID and io.branch-labs.Branchster is the Bundle ID.
• paths: Array of strings that specify which paths are included or excluded from association. You can use NOT (before the path – as in the example JSON above) to disable paths. In this case, all the links on this path will go to the web instead of opening the app. You can use * as a wildcard to enable all paths in a directory and ? to match a single character (/archives/201?/ example in the sample JSON). Please note that these strings are case sensitive and that query strings and fragment identifiers are ignored.

* Don’t know what your Team ID is? Head over to https://developer.apple.com/account and retrieve it from the Membership section.

** To retrieve the Bundle ID, head over to your Xcode project, select project and then the ‘General’ tab.

Hosting the AASA File on Your Domain

Once you are ready with your AASA file, you can now host it on your domain either at https://<<yourdomain>>/apple-app-site-association or at https://<<yourdomain>>/.well-known/apple-app-site-association.

While hosting the AASA file, please ensure that the AASA file:

• Is served over HTTPS.
• Uses application/json MIME type.
• Does not have an appended .json to the apple-app-site-association file name.
• Has a size not exceeding 128 Kb (requirement in iOS 9.3.1 onwards).

Supporting Multiple Apps on the Same Domain

You can support multiple apps on the same domain. To do that, you’d need to add a new appID, path dictionary to the details array in the AASA file to look something like this:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "3XXXXX9M83.io.branch-labs.Branchster",
        "paths": [ "NOT /e/*", "*", "/", “/archives/201?/* ]
      },
      {
         "appID": "3ZZZZZ9M94.io.branch-test.Branch",
         "paths": [ "NOT /e/*", "*", "/", “/archives/200?/* ]
      }
    ]
  }
}

If two or more apps associate with the same content path on the website then the order of the appID, paths dictionary in the details array will determine which app will get precedence.

Supporting Multiple Domains for the Same App

Each domain that the app needs to support has to have its own apple-app-site-association file. If the content served by domains is different, then the contents of the file will also be different to support the respective paths. Otherwise, the same AASA file can be used but it needs to be accessible on every supported domain. Also note that even though example.com and www.example.com might be serving the same content, you need to ensure that the AASA file is hosted on both these domains.

At Branch, we live and breathe deep links and have created an AASA validator to help you build your valid AASA file. You can find it here: https://branch.io/resources/aasa-validator/.

If you are using Branch links, you can bypass all the steps of building, validating, hosting and managing an AASA file by checking a single box on the Branch dashboard. We take care of all everything else under the hood for you.