Configuring an associated domain

Overview

The system uses associated domains to initiate a secure association between your app and specific domains so they can share saved passwords, perform Handoff activities, and support universal links that allow users to open your app in a specific context and quickly complete their current task. To create such an association, you configure your app with the necessary entitlements by using Xcode to define associated domains, and then serve a special file from your web server that the system requires in order to verify those entitlements.

Before you can define associated domains and the services they provide, follow the steps in the Add a capability section of Adding capabilities to your app to add the capability to your app’s target, making sure you select the Associated Domains capability from Xcode’s Capabilities library. For watchOS apps with separate WatchKit extensions, add the capability to the WatchKit Extension target.

[Image]

If not already present, Xcode updates your target’s entitlements file to include the Associated Domains Entitlement, which is an array that contains each associated domain you define. If you enable the “Automatically manage signing” option for your target, Xcode also updates your app’s App ID in your developer account and generates and downloads an updated provisioning profile.

Define a service and its associated domain

When you want your app and one or more of your websites to interact using predefined services, define an associated domain by performing the following steps. Xcode automatically updates the com.apple.developer.associated-domains array in your target’s entitlements file to include those you define.

1. Select your project in Xcode’s Project navigator.

2. Select the app’s target in the Targets list.

3. Click the Signing & Capabilities tab in the project editor.

4. Find the Associated Domains capability.

5. Click the Add button (+) to insert a service-domain placeholder.

6. Double-click the inserted placeholder to edit it.

Update the placeholder to contain the service your app supports and its associated domain, which must be in the following format:

<service>:<fully qualified domain>

[Image]

Only include the top-level domain and, where necessary, the subdomain; don’t include path and query components, or a trailing slash.

The following table describes the services that associated domains support:

Provide an Apple App Site Association file

When the user installs your app that contains associated domains, the system fetches the corresponding Apple App Site Association (AASA) file from an Apple-managed content delivery network (CDN) and uses its JSON contents to verify those associated domains. If the CDN doesn’t store a copy of that file, or has an outdated version, it automatically connects to your server and retrieves the latest version.

After you define your app’s associated domains in Xcode, you must create this file and serve it using HTTPS from your website’s .well-known directory. For more information, see Add the associated domain file to your website.

Enable alternate mode for unreachable servers

If you use a private web server while developing your app that’s unreachable from the public internet, enable alternate mode — an option you specify that allows the system to bypass Apple’s CDN and fetch the AASA file directly from your web server.

Follow these steps to enable alternate mode on a specific associated domain:

1. Select your project in Xcode’s Project navigator.

2. Select the app’s target in the Targets list.

3. Click the Signing & Capabilities tab in the project editor.

4. Find the Associated Domains capability.

5. Double-click the associated domain in the Domains list to edit it.

6. Append the string ?mode=<alternate mode> to the associated domain. Replace <alternate mode> with one of the modes shown in the list below.

7. Press Return to save the updated associated domain.

[Image]

The following table describes the alternate modes that associated domains support:

See Also

Data management

• Configuring app groups
• Configuring iCloud services