Swift – How to integrate the AASA file with the hosting server for all subdomains

Are you worried about integrating the AASA file with the hosting server for all subdomains and supporting wildcards in associated domains?

Apple's App site association file

Problem Statement:-

How to integrate the AASA (Apple-App-Site-Association) file with the hosting server for all subdomains.

Linking is essential in today’s tech world. Deep linking facilitates in a clickable link that helps to navigate to the desired resource. Universal links manage links to open a specific app page instead of handling the URL in Safari. These are useful shortcuts that help to improve the user experience. Let’s now find how to integrate the AASA file with the hosting server for all subdomains.

Description of the Issue:-

I worked on Swift when I encountered this issue, where the deep links were not functioning correctly. I researched and collected information related to the issue I faced and tried the possible ways to integrate the AASA file with the hosting server for all subdomains.

The Solution Offered:-

I added the AASA file in the hosting server on the main domain by following the steps mentioned below.

1. Configure your app to register approved domains:-

  • Register your app at apple.com.
  • Enable ‘Associated Domains’ on your app identifier.
  • Enable ‘Associated Domain’ on in your Xcode project
  • Add domain into the project under capabilities of associated domains ex:
    • applinks:abc.xyz  //main domain
    • applinks: *.abc.xyz // subdomains

2. Configure your website to host the ‘apple-app-site-association’ file

  • The AASA (apple-app-site-association) is a file that lives on your website and associates your website domain with your native app.
  • The AASA file contains a JSON object with a list of apps and the URL paths on the domain that should be included or excluded as Universal Links. Here is a sample AASA file:
“applinks”: {
  “apps”: [],
  “details”: [
      “appID”: “JHGFJHHYX.com.facebook.ios”,
      “paths”: [
  • appID: Built by combining your app’s Team ID (go to https://developer.apple.com/account/#/membership/ to get the teamID) and the Bundle Identifier. In the example above, JHGFJHHYX is the Team ID, and com.facebook.ios is the Bundle ID.
  • Paths: Array of strings that specify which paths are included or excluded from association. You can use NOT (before the path — as in the example JSON above) to disable paths. In this case, all the links on this path will go to the web instead of opening the app. You can use * as a wildcard to enable all paths in a directory (apple doc says: Use * to specify your entire website) and match a single character (/archives/201?/ example in the sample JSON). Please note that these strings are case sensitive and that query strings and fragment identifiers are ignored.

3. Hosting the AASA File on Your Domain

  • Once you are ready with your AASA file, you can now host it on your domain either at https://<<yourdomain>>/apple-app-site-association or at https://<<yourdomain>>/.well-known/apple-app-site-association.
  • Upload the apple-app-site-association file to your HTTPS web server. You can place the file at the root of your server or in the .well-known subdirectory.

Important: iOS will only attempt to fetch the AASA file over a secure connection (HTTPS).

  • while hosting the AASA file, please ensure that the AASA file:
  • Is served over HTTPS.
  • Uses application/json MIME type.
  • Don’t append .json to the apple-app-site-association filename.
  • Has a size not exceeding 128 Kb (a requirement in iOS 9.3.1 onwards).


Go to the following link and enter your domain name. It will check if the AASA file is valid and is accessible.

Link: https://branch.io/resources/aasa-validator/#resultsbox

5. Preparing Your App to Handle Universal Links

  • When a user taps a universal link, iOS launches your app and sends it an NSUserActivity object that you can query to find out how your app was launched.
  • To support universal links in your app, take the following steps
    • Add an entitlement that specifies the domains your app supports.
    • Update your app delegate to respond appropriately when it receives the NSUserActivity
  • As mentioned above, in Xcode, open the Associated Domains section in the Capabilities tab and add an entry for each domain that your app supports, prefixed with applinks.
    example: applinks:www.mywebsite.com
  • Apple doc says to limit this list to no more than about 20 to 30 domains.
  • To match all subdomains of an associated domain, you can specify a wildcard by prefixing *. before the beginning of a specific domain (the period is required). Domain matching is based on the longest substring in the applinks entries. For example, if you specify the entries applinks:*.mywebsite.com and applinks:*.users.mywebsite.com, matching for the domain emily.users.mywebsite.com is performed against the longer *.users.mywebsite.com entry. Note that an entry for *.mywebsite.com does not match mywebsite.com because of the period after the asterisk. To enable matching for both *.mywebsite.com and mywebsite.com, you need to provide a separate applinks entry for each.
  • After you do all these steps perfectly, when you click a universal link, the app will open up and the method application:continueUserActivity:restorationHandler will get called in Appdelegate.
  • When iOS launches your app after a user taps a universal link, you receive an NSUserActivity object with an activityType value of NSUserActivityTypeBrowsingWeb. The activity object’s webpageURL property contains the URL that the user is accessing. The webpage URL property always has an HTTP or HTTPS URL, and you can use NSURLComponents APIs to manipulate the components of the URL.

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
print(“Continue User Activity called: “)
if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
let url = userActivity.webpageURL!
//handle url and open whatever page you want to open.
return true

6. Testing

Add the universal link to an email and send it to the testing device. Or you can save it in the notes app. This is what I did for testing.
Technologies or frameworks or tools – Swift, Xcode, Apache, NgInx
Swift is a powerful and intuitive programming language developed by Apple Inc. for iOS, iPadOS, macOS, watchOS, tvOS, and Linux. Using Swift to write codes in interactive and fun. It is also safe and faster than other programming languages. Most of the developers love to code using Swift and choose iOS development because of the dynamic nature of the language. Moreover, as Swift is a single programming language for all the Apple products, gaining experience is simple and faster.
Platforms (Web, Mobile, Etc.)iOS
Soft Suave is the top web and mobile app development company in India that houses developers from the top 1% of the talent pool in the world. The developers are highly-experienced, and their expertise extends from all front-end to back-end technologies. If you are worried about integrating the AASA file with the hosting server for all subdomains and support wildcards in associated domains, get in touch with Soft Suave and hire iOS developers now.