Article

Supporting Associated Domains in Your App

Connect your app and a website in order to provide both a native app and a browser experience.

Overview

Associated domains establish a secure association between domains and your app so you can share credentials or provide features in your app based on your website. For example, an online retailer may offer an app to accompany their website in order to enhance the user's experience.

Additionally, 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 still get all of the same information provided to them in a web browser instead of the native experience.

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

Add the Associated Domains Entitlement

To set up the entitlement in your app, open the project’s Capabilities tab and enable Associated Domains. This step adds the Associated Domains Entitlement to your app as well as the associated domains feature to your app ID. For more information, see Configure associated domains.

To add your domain to the entitlement, click Add (+) at the bottom of the Domains table in order to add a placeholder domain with the appropriate prefix for the service your app will support. Replace the placeholder with your site’s domain, retaining the prefix.

Screenshot showing how to add the associated domains for your app.

Add the domains with which you want your app to share credentials. To match all subdomains of an associated domain, specify a wildcard with the prefix *. before the beginning of a specific domain (the period is required).

Each domain you specify uses the following format:

<service>:<fully qualified domain>

Add the Apple App Site Association File

Next, add the Apple App Site Association file to your website. To do this, create a file named apple-app-site-association (without an extension). Update the file to contain the JSON representation of a dictionary listing the app identifiers associated with your domain for the applinks service.

The following JSON representation demonstrates the breadth of options available when constructing the association file.

{
  "applinks": {
      "details": [
           {
             "appIDs": [ "ABCDE12345.com.example.app", "ABCDE12345.com.example.app2" ],
             "components": [
               {
                  "#": "no_universal_links",
                  "exclude": true,
                  "comment": "Matches any URL whose fragment equals no_universal_links and instructs the system not to open it as a universal link"
               },
               {
                  "/": "/buy/*",
                  "comment": "Matches any URL whose path starts with /buy/"
               },
               {
                  "/": "/help/website/*",
                  "exclude": true,
                  "comment": "Matches any URL whose path starts with /help/website/ and instructs the system not to open it as a universal link"
               }
               {
                  "/": "/help/*",
                  "?": { "articleNumber": "????" },
                  "comment": "Matches any URL whose path starts with /help/ and which has a query item with name 'articleNumber' and a value of exactly 4 characters"
               }
             ]
           }
       ]
   },
   "webcredentials": {
      "apps": [ "ABCDE12345.com.example.app" ]
   }
}

The appIDs and apps keys specify the application identifiers for the apps that are available for use on this website and with the given service type. Use the following format for the values in these keys:

<Application Identifier Prefix>.<Bundle Identifier>

The details dictionary should only be specified for the applinks service type. Other service types do not use it.

The components key is an array of dictionaries that provides pattern matching for components of the URL. The possible keys and their values include:

"/"

Matches the specified pattern to a URL's path component. The value is a string.

"?"

Matches the specified pattern to a URL's query component. The value is a string or a dictionary. If it is a dictionary, the keys are NSURLQueryItem query item names and the values are patterns for those specific query items. If a query item is not present in a URL it is assumed to have a value equal to the empty string.

"#"

Matches the specified pattern to a URL's fragment component. The value is a string.

"exclude"

Stops pattern-matching and prevents the universal link from opening if the URL matches the pattern dictionary.

"comment"

Specifes text ignored by the system.

After you construct the association file, place it in your site’s .well-known directory. The file’s URL should match the following format:

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

You must host the file using https:// with a valid certificate and without using any redirects.

Validate the Apple App Site Association File

When your app is installed, the system attempts to download and verify the association file from the domains listed in your entitlement. For each domain, the system appends /.well-known/apple-app-site-association to its name. With this new URL, the system downloads the contents and ensures the file includes the app’s application identifier.

A validation may fail and the association will be denied if:

  • The JSON file is invalid or doesn’t contain the application identifier.

  • The server returns a 400-499 code.

Redirects to something other than secure HTTP will fail.

If the server returns a 500-599 code, the system assumes that the file is temporarily unavailable and may retry again.

After an app successfully associates with a domain, it remains associated until the app is deleted from the device. During development, delete your app from your testing device each time you update the association file to immediately see your changes.

Add the Apple App Site Association File for iOS 12 and Earlier

If your app runs on iOS 12 or earlier, you must use a different apple-app-site-association file. Include the following JSON with your domain for the webcredentials service.

{
  "applinks": {
      "apps": [],
      "details": [
           {
             "appID": "ABCDE12345.com.example.app",
             "paths": [ "/buy/*", "NOT /help/website/*", "/help/*" ]
           }
           {
             "appID": "ABCDE12345.com.example.app2",
             "paths": [ "/buy/*", "NOT /help/website/*", "/help/*" ]
           }
       ]
   },
   "webcredentials": {
      "apps": [ "ABCDE12345.com.example.app" ]
   }
}

You can include both paths and components array in the same details dictionary.

Topics

Entitlements

Associated Domains Entitlement

The associated domains for specific services, such as shared web credentials and universal links.

Key: com.apple.developer.associated-domains

See Also

Essentials

About the Password AutoFill Workflow

Learn how Password AutoFill interacts with both iOS and web apps.