Skip Navigation

Supporting associated domains

Connect your app and a website 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 from your website. 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.

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.

Add the associated domain file to your website

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

To add the associated domain file to your website, create a file named apple-app-site-association (without an extension). Update the JSON code in the file for the services you support on the domain. For universal links, be sure to list the app identifiers for your domain in the applinks service. Similarly, if you create an App Clip, be sure to list your App Clip’s app identifier using the appclips service.

The following JSON code represents the contents of a simple association file:

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


    "appclips": {
        "apps": ["ABCDE12345.com.example.MyApp.Clip"]
    }
}

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

<Application Identifier Prefix>.<Bundle Identifier>

The details dictionary only applies to the applinks service type; other service types don’t use it. The components key is an array of dictionaries that provides pattern matching for components of the URL.

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 with no redirects.

Add the associated domains entitlement to your app

To set up the entitlement in your app, 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.

To add your domain to the entitlement, click Add (+) at the bottom of the Domains table to add a placeholder domain. Replace the placeholder with the appropriate prefix for the service your app supports and your site’s domain. Make sure to only include the desired subdomain and the top-level domain. Don’t include path and query components or a trailing slash (/).

A screenshot of the Associated Domains table in Xcode with two domains listed.

Add the domains that share credentials with your app. For services other than appclips, you can prefix a domain with *. to match all of its subdomains.

Each domain you specify uses the following format:

<service>:<fully qualified domain>

Starting with macOS 11 and iOS 14, apps no longer send requests for apple-app-site-association files directly to your web server. Instead, they send these requests to an Apple-managed content delivery network (CDN) dedicated to associated domains.

While you’re developing your app, if your web server is unreachable from the public internet, you can use the alternate mode feature to bypass the CDN and connect directly to your private domain.

You enable an alternate mode by adding a query string to your associated domain’s entitlement as follows:

<service>:<fully qualified domain>?mode=<alternate mode>

For more information about alternate modes, see Associated Domains Entitlement. For information about universal links, see Allowing apps and websites to link to your content. For information about Handoff, see Implementing Handoff in Your App. For information about App Clips, see Configuring the launch experience of your App Clip.

Topics

Current page is Supporting associated domains