Set up associated domains to share credentials with a website related to your app.
A domain is a website. Often you will want to associate your website with your app because they are often different versions of the same app or are related and want to share data. To associate a website with an app, you will need to have a file on your website and an entitlement in your app.
An associated domain matches the
Associated Domains Entitlement in your app with an
apple-app-site-association file on your website.
It’s important to establish an association between domains and your app if you want to share credentials or if features in your app are based 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
webcredentials: prefix. 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.
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
Use the following format for the app identifiers:
Place this file either in your site’s .
well-known directory, or directly in its root directory. If you use the
.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 on an iOS device, the system attempts to download and verify the association file from the domains listed in your entitlement. For each domain, iOS 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 300-499 code.
If the server returns a 500-599 code, the system assumes that the file is temporarily unavailable and tries again. By default, the system retries every three hours, up to eight times.
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.
If the system successfully verifies the associated domain, Password AutoFill can display credentials from that domain in the QuickType bar. If you want to access and modify the shared web credentials, call the