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.
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.
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-associationfile is added under
.well-knownsubdirectory of the website hosting it. The address of the file should be
- The file should be a valid JSON file without any extension and is served from an
HTTPSaddress. This means you do not need to append
- If you plan on supporting multiple domains or subdomains then there should be a separate
apple-app-site-associationfile 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
- Before adding data to the file, gather the following so you have it ready when you create your
- 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
appIDis a combined string value of TeamID with Bundle Identifier of your app. So an with team id as ABCD1234 and bundle identifier as
appIDin the file as ABCD1234.com.apple.wwdc
?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.