Apple Universal Link setup in iOS

4 min readSep 8, 2022

Overview

We’ll explore how to setup universal links in iOS and on the server side so you are able to open your app when a user goes to a your universal website link.

What are universal links?

Universal links are web links which point to some content on the web and in your app. Universal links are different from deeplink as they are pure web links where as deeplinks will always start with yourAppScheme:// and open the app.

Universal links allows user to visit either the web link or on their iOS device if the app is configured to utilize universal links it will prompt to open the app instead and can take a user to the proper content in the app for a much richer experience.

Setup

There are few steps on setting up universal link where we need to configure both our iOS App and Server to support universal links.

iOS App Setup

Setting the iOS App to accept universal links to take user to the correct view on the app.

A. Update Associated Domains Entitlement

Enable Associated Domains by editing your App ID config in developer portal (developer.apple.com → identifiers)

B. Add Associated Domains to the iOS App

Note: Make sure to replace universallink.page with your own domain name

C. Debug Mode

In order to enable debug mode we can append ?mode=developer at the end of our domain url in XCode. It will allow the system to fetch apple-app-site-association file faster and update the system while we make changes to apple-app-site-association file and test out universal links.

D. Handle Universal Links in iOS App

Use the following method(s) to handle universal links in an iOS application. The API you use depends on the type of application you are working on and whether it supports AppDelegate or SceneDelegate.

Server configuration

We need to upload a JSON file called apple-app-site-association on the server which will define the type of links that will act as universal links for the iOS App.

Name of the file should be apple-app-site-association
The apple-app-site-association file is added under .well-known subdirectory of the website hosting it. The address of the file should be /.well-known/apple-app-site-association
The file should be a valid JSON file without any extension and is served from an HTTPS address. This means you do not need to append .jsonto the apple-app-site-association filename.
If you plan on supporting multiple domains or subdomains then there should be a separate apple-app-site-association file for each domain with unique content that your app supports. Also, each domain and subdomain requires its own entry in the [Associated Domains Entitlement]
The uncompressed file size should be no greater than 128 KB
The file should have MIME type as application/json
Before adding data to the file, gather the following so you have it ready when you create your apple-app-site-association file.

Team ID which is the same value that’s associated with the “application-identifier” key in your app’s entitlements after you build. This can be found under developer.apple.com portal → Team ID
Bundle identifier which can be found in XCode under your target → scheme

8. Below is a sample apple-app-site-association file with explanation of what each items means

appID is a combined string value of TeamID with Bundle Identifier of your app. So an with team id as ABCD1234 and bundle identifier as com.apple.wwdc will have appID in the file as ABCD1234.com.apple.wwdc
* and ? are wildcard in the pattern strings
* matches 0 or more characters and in terms of paths if we only have * then it means having a universal link for your entire website. Anytime a user opens your website it will be prompted to open the app.
? matches exactly any one character
* will allow us to match at least one character
/ represent specific path if they are not followed by * symbol. This means when a user goes /wwdc/news/ it will prompt to open the the app.

9. In recent years Apple has also introduced another version of apple-app-site-association file which is specific to iOS 13.5 and above with more options to configure. However, the older version should still work. Below is an example of contents of the newer version of apple-app-site-association file.

Note: For iOS 14 and above, Apple CDN will fetch the apple-app-site-association file from the server as long as it is behind an HTTPS connecting and configured properly. Look for Apple’s Bot (“AASA-Bot/1.0.0”) to read the change in your server console logs. This can take anywhere from few minutes to a few hrs to get the change.

Ref Links: