Connect your app and a website in order to provide both a native app and a browser experience.
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.
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:
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
The following JSON representation demonstrates the breadth of options available when constructing the association file.
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:
details dictionary should only be specified for the
applinks service type. Other service types do not use it.
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
NSURLQueryquery 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.
Stops pattern-matching and prevents the universal link from opening if the URL matches the pattern dictionary.
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:
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
You can include both
components array in the same