Logo for tanaschita.com

Quick guide on associated domain files for iOS development

Learn how to connect the iOS app with its related website to support features like universal links, shared web credentials or app clips.

25 Jul 2022 · 5 min read

Associated domains establish a secure association between a website and an iOS application allowing us to support features like universal links, shared web credentials with password auto fill or app clips.

In this guide, we'll look at how to support associated domains.

Sponsorship logo
Using Proxyman to inspect network traffic
Proxyman is a native debugging proxy that can act as a man-in-the-middle between your application and web server. You can use its powerful toolkit to inspect network calls and debug your application on Mac, iOS Simulator, or remote devices effortlessly.
CLICK TO LEARN MORE

Steps to setup associated domains

To support associated domains, the following steps are required:

  1. Creating and configuring an associated domain file.
  2. Adding the associated domain file to the related website.
  3. Adding an associated domain entitlement to the iOS app.

Let's look at each of those steps in more detail.

1. Creating and configuring an associated domain file

The first step requires creating a file named apple-app-site-association without an extension and configuring it by using the JSON format for services we’ll support on the domain.

The root of the associated domain file consists of 3 keys:

{
"applinks": {
},
"webcredentials": {
},
"appclips": {
}
}

The applinks key

The applinks key is used to define universal links. When users tap a universal link, they are redirected to a specific part of an iOS application if installed. If the app is not installed, the link opens in a browser, allowing the connected website to handle it.

{
"applinks":{
"details":[
{
"appIDs":[
"APPIDPREFIX.com.tanaschita.exampleApp"
],
"components":[
{
"/": "birds",
}
]
}
]
}
}

The example above shows how the applinks object might be configured. Checkout this guide on supporting universal links to learn more about those configuration options and on how to handle universal links in the app.

The webcredentials key

The webcredentials key is used for shared web credentials. Users are able to save their username and password in their iCloud keychain when logging into websites. When they run a native app to access the same account at some point, the app has access to the credentials stored for the website so there is no need to reenter them.

"webcredentials": {
"apps": [ "APPIDPREFIX.com.tanaschita.exampleApp" ]
}

With shared web credentials setup, we can use Apple's Password AutoFill feature to simplify login and signup tasks in our iOS applications. Checkout this guide on supporting Password AutoFill (coming soon) to learn more.

The appclips key

The appclips key is used to support App Clips. An app clip is a lightweight version of the iOS application offering users access to certain functionality. It lets users complete a quick task like renting a bike or ordering food - even before installing the full app.

{
"appclips": {
"apps": ["APPIDPREFIX.com.tanaschita.exampleApp.appClip"]
}
}

The apps key is an array that contains the app identifier of the App Clip. Checkout this guide on supporting App Clips (coming soon) to learn more.

2. Adding the associated domain file to the related website

After configuring the association file the way we need, the second step is to place it into the website's .well-known directory.

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

The file's URL should match the format shown above.

3. Adding an associated domain entitlement to the iOS app

The last step is to add an Associated Domains entitlement to the iOS application. We can add capabilities by opening the app target's Signing & Capabilities tab in Xcode.

Adding capabilities in Xcode.
Adding capabilities in Xcode.

After selecting the Associated Domains entitlement, we can add domains in the following format:

<service>:<domain>

Adding an associated domains capability in Xcode.
Adding an associated domains capability in Xcode.

A capability grants our app access to an app service provided by Apple. In our case, the available services match the ones we can configure in the apple-app-site-association file:

Enabling alternate mode for testing

Starting with iOS 14, apps request apple-app-site-association files from an Apple-managed content delivery network (CDN) instead directly from the web server. The CDN regularly connects to the web server to obtain the latest version.

During development, the web server might be not publicly reachable yet. To still be able to test, we can enable the alternate mode feature to bypass the CDN and connect directly to the server by adding the following configuration:

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

The value for alternate mode can be one of the following:

The alternate mode should only be used during development.

Sponsorship logo
Using Proxyman to inspect network traffic
Proxyman is a native debugging proxy that can act as a man-in-the-middle between your application and web server. You can use its powerful toolkit to inspect network calls and debug your application on Mac, iOS Simulator, or remote devices effortlessly.
CLICK TO LEARN MORE

Newsletter

Image of a reading marmot
Subscribe

Like to support my work?

Say hi

Related tags

Articles with related topics

associated domains

security

swiftui

ios

Implementing Password AutoFill for an iOS application

Learn how to activate Apple's Password AutoFill for SwiftUI and UIKit.

15 Aug 2022 · 3 min read

Latest articles and tips

© 2022 tanaschita.com

Privacy policy

Impressum