Skip to main content
Sign in

Universal Linking In iOS

  • Updated

Seamlessly link to content inside your iOS app 

Strengthen the relationship between your website and your mobile app by allowing your users to automatically open up a web URL inside your app experience. 

 

How to Set Up Universal Linking on iOS

  1. Configure your website to host the ‘apple-app-site-association’ file. 
  2. 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. Example: http://yourdomain.com/.well-known/apple-app-site-association
  3. Reach out to the Pro Services team by emailing us at "pro@mazsystems.com" to let us know you would like to enable Universal Linking. We'll have to register your approved domains in your app and schedule an app update once you completed the steps above. 

There are three steps you need to take:

  • Create an apple-app-site-association file that contains JSON data about the URLs that your app can handle.
  • 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.
  • Prepare your app to handle universal links. *Handled by Pro Services. 

For more information reference Apple Universal Links support documentation here. 

 

Creating and Uploading the Association File

To create a secure connection between your website and your app, you establish a trust relationship between them. You establish this relationship in two parts:

  • An apple-app-site-association file that you add to your website
  • A com.apple.developer.associated-domains entitlement that you add to your app (this part is described in Preparing Your App to Handle Universal Links). *Handled by Pro Services. 

You can learn more about how your app and website can share credentials in Shared Web Credentials Reference .

 

NOTE: If your app runs in iOS 9 or later and you use HTTPS to serve the apple-app-site-association file, you can create a plain text file that uses the application/json MIME type and you don’t need to sign it. If you support Handoff and Shared Web Credentials in iOS 8, you still need to sign the file as described in Shared Web Credentials Reference .

 

You need to supply a separate apple-app-site-association file for each domain with unique content that your app supports. For example, apple.com and developer.apple.com need separate apple-app-site-association files, because these domains serve different content. In contrast, apple.com and www.apple.com don’t need separate site association files—because both domains serve the same content—but both domains must make the file available. For apps that run in iOS 9.3.1 and later, the uncompressed size of the apple-app-site-association file must be no greater than 128 KB, regardless of whether the file is signed.

In your apple-app-site-association file, you specify the paths from your website that should be handled as universal links along with those that should not be handled as universal links. Keep the list of paths fairly short and rely on wildcard matching to match larger sets of paths. Listing 6-1 shows an example of an apple-app-site-association file that identifies three paths that should be handled as universal links.

 

Creating an apple-app-site-association file

  1. {
  2.     "applinks": {
  3.         "apps": [],
  4.         "details": [
  5.             {
  6.                 "appID": "9JA89QQLNQ.com.apple.wwdc",
  7.                 "paths": [ "/wwdc/news/", "/videos/wwdc/2015/*"]
  8.             },
  9.             {
  10.                 "appID": "ABCD1234.com.apple.wwdc",
  11.                 "paths": [ "*" ]
  12.             }
  13.         ]
  14.     }
  15. }

NOTE: Don’t append .json to the apple-app-site-association filename.

 

The apps key in an apple-app-site-association file must be present and its value must be an empty array, as shown in Listing 6-1. The value of the details key is an array of dictionaries, one dictionary per app that your website supports. The order of the dictionaries in the array determines the order the system follows when looking for a match, so you can specify an app to handle a particular part of your website.

Each app-specific dictionary contains an appID key and a paths key. The value of the appID key is the team ID or app ID prefix, followed by the bundle ID. (The appID value is the same value that’s associated with the “application-identifier” key in your app’s entitlements after you build it.) The value of the paths key is an array of strings that specify the parts of your website that are supported by the app and the parts of your website that you don’t want to associate with the app. To specify an area that should not be handled as a universal link, add “NOT ” (including a space after the T) to the beginning of the path string. For example, the apple-app-site-association file shown in Listing 6-1 could prevent the /videos/wwdc/2010/* area of the website from being handled as a universal link by updating the paths array as shown here:

  1. "paths": [ "/wwdc/news/", "NOT /videos/wwdc/2010/*", "/videos/wwdc/201?/*"]

Because the system evaluates each path in the paths array in the order it is specified—and stops evaluating when a positive or negative match is found—you should specify high priority paths before low priority paths. Note that only the path component of the URL is used for comparison. Other components, such as the query string or fragment identifier, are ignored.

There are various ways to specify website paths in the apple-app-site-association file. For example, you can:

  • Use * to specify your entire website
  • Include a specific URL, such as /wwdc/news/, to specify a particular link
  • Append * to a specific URL, such as /videos/wwdc/2015/*, to specify a section of your websiteIn addition to using * to match any substring, you can also use ? to match any single character. You can combine both wildcards in a single path, such as /foo/*/bar/201?/mypage.

NOTE: The strings you use to specify website paths in the paths array are case sensitive.

 

After you create the apple-app-site-association file, upload it to the root of your HTTPS web server or to the .well-known subdirectory. The file needs to be accessible via HTTPS—without any redirects—at https://<domain>/apple-app-site-association or https://<domain>/.well-known/apple-app-site-association. 

 

Apple App Site Association (AASA) Validator

 

Go to the following link and enter your domain name. This site will validate if the AASA file is valid and is accessible. 

Once your domain name is valid let the Pro Services team know at "pro@mazsystems.com" and we'll complete the app side setup from there!