Updated for Xcode 14 - SwiftUI

What are Associated Domains?

With Associated Domains you can connect your app and a website to provide both a native app and a browser experience. For example, an online retailer may offer an app to accompany their website and enhance the user experience.

Shared web credentials, universal links, Handoff, and App Clips all use associated domains. Associated domains provide the underpinning to universal links, a feature that allows an app to present content in place of all or part of its website. Users who don’t download the app get the same information in a web browser instead of the native app.

How to setup Associated Domains

There are multiple steps to support this feature, so I'll break it down below.

1. Add the associated domain file to your website
2. Add the associated domains entitlement to your app

Add file to the website

When a user installs your app, the system attempts to download the associated domain file and verify the domains in your entitlement.

To associate a website with your app, you need to have the associated domain file on your website and the appropriate entitlement in your app. The apps in the apple-app-site-association file on your website must have a matching Associated Domains Entitlement.

If your site uses multiple subdomains (such as example.com, www.example.com, and support.example.com), each requires its own entry in the Associated Domains Entitlement, and each must serve its own apple-app-site-association file.

1. Create a file named apple-app-site-association (without an extension).
2. Make sure the path is the following: https://<<yourdomain>>/.well-known/apple-app-site-association

Your file would look like:

{
   "webcredentials": {
      "apps": ["YOUR_TEAM_ID.BUNDLE_IDENTIFIER"]
   }
}

To find your Team id, go here
You do not need to sign the file using the steps described here.

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

• Is served over HTTPS.
• Uses application/json MIME type
  ( This means when you go to the full url of the file, the header response should be in that format, see common errors below if you still have doubts)
• 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)

When you are done, use one of these tools to validate your file:

• Sierra validator (use this one only until the step: Your file must be served with content type... because it's outdated, but still shows some useful info.)
• Apple App Search API Validation Tool
• AASA validator

Here's an example of how it should look like:
Note: Using one of the validators above, I got the message Error cannot parse app site association, however inside the app works correctly for password autofill.

https://road2crypto.com/.well-known/apple-app-site-association

Add the associated domains entitlement to your app

1. Enabled the Associated Domain entitlements on your App ID configuration.

Open the target’s Signing & Capabilities tab in Xcode and add the Associated Domains capability. If they’re not already present, this step adds the Associated Domains Entitlement to your app and the associated domains feature to your app ID.

How often is apple-app-site-association updated by app on device?

I've found that the apple-app-site-association file is fetched when the app is installed on the device. So essentially, every install/update will trigger a download of the file. You can simulate this by deleting the app from your device and reinstalling it. Source

Developer-Mode on Xcode

If you want Apple to call your app-site-association file each time the app is installed, on the entitlements above, change it to: applinks:[domain]?mode=developer

Debugging

You can verify/debug on Xcode if your domains are correctly being called by looking at the logs in the console:

1. Open Xcode and go to Devices and Simulators
2. Tap on Open Console (if it doesn't appear with the simulator, connect a real device, then select simulator)

3. With the simulator to use selected, tap on Start to record the logs and run/install the app, once it installs, tap Stop on the console since the associated domains are installed at lunch.
4. Search on the console for Beginning data task, it will look something like this:

Common errors

• The content type has to be application/json

Here are some solutions for Nginx, Github Pages with Cloudflare, Wordpress, AWS Cloudfront

Extra Reading

Password AutoFill workflow

If you know anyone who might need this, share it 🙌🏻

With love and respect,
Arturo 👨🏻‍💻