Understanding associated domains in iOS

Associated domains create a secure, system-managed connection between an iOS app and its matching website, allowing us to support features like universal links, shared web credentials with password auto fill or app clips.

All of these rely on the same mechanism: an apple-app-site-association file on the website + an associated domains entitlement in the app.

In this artile, we walk through how the system works and how to configure everything correctly.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

What associated domains are

In simple terms, associated domains allow iOS to verify: "This website and this app belong together."

Once verified, we can implement features such as:

• Universal Links: let us route specific URLs directly into the app instead of opening them in a browser. If the app is installed, we can navigate the user to the appropriate screen immediately. If it is not installed, the URL opens on the website as usual.
• Shared Web Credentials with Password AutoFill: our app can access authentication information a user previously saved in iCloud Keychain while using the connected website. When a user has already signed in on the web, the app can request the username and password and fill them automatically
• App Clips: an app clip is a lightweight version of the iOS application offering users access to certain functionality. It lets users complete a quick task like renting a bike or ordering food - even before installing the full app.

Setting this up requires two parts:

1. A JSON file (apple-app-site-association) hosted on the website
2. A matching entitlement inside the app

Creating and configuring an associated domain file

The first step requires creating a file named apple-app-site-association without an extension and configuring it by using the JSON format. Its top-level structure typically contains keys for the services we want to support:

{
  "applinks": {},
  "webcredentials": {},
  "appclips": {}
}

A example configuration for universal links might look as follows:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["APPIDPREFIX.com.tanaschita.exampleApp"],
        "components": [
          {
            "/": "birds"
          }
        ]
      }
    ]
  }
}

It tells iOS that any URL of this website whose path begins with /birds should be handled by our app.

Adding the associated domain file to the related website

After configuring the association file the way we need, the second step is to place it into the website's .well-known directory:

https://<domain>/.well-known/apple-app-site-association

The file's URL should match the format shown above. The file:

• must be served over HTTPS
• must not have a .json extension
• should be served with a JSON content type, which Apple expects when parsing

Adding an associated domain entitlement to the iOS app

Next, we can add the entitlement to our app:

1. Open the app target in Xcode.
2. Navigate to Signing & Capabilities.
3. Add Associated Domains.

Inside the capability, we can add entries using this format:

applinks:example.com
webcredentials:example.com
appclips:example.com

Enabling alternate mode for testing

Apps request apple-app-site-association files from an Apple-managed content delivery network (CDN) instead directly from the web server. The CDN regularly connects to the web server to obtain the latest version.

During development, the web server might be not publicly reachable yet. To still be able to test, we can enable the alternate mode feature to bypass the CDN and connect directly to the server by adding the following configuration:

applinks:example.com?mode=developer

Checkout this article using associated domains alternate mode to learn more.