iOS Universal Links FAQ

Universal Links are Apple’s new deep-links, designed to replace the older URI-scheme deep-linking method. They are available for devices running iOS 9 and above.

While Universal Links allow for deep-linking behavior similar to URI schemes, they function very differently behind the scenes. Universal Links look like normal HTTPS URLs, e.g. “https://www.linkedin.com”. When a user clicks a Universal Click, the user’s device opens the app that the link was configured for. If the app is not installed on the device, the user is taken to the actual URL in their mobile browser.

See Apple’s Developer documentation.

As an app developer, do the following to enable Universal Links in your app:

1. Enable Associated Domains in Your Apple Developer Account

   Log into your Apple developer account and go to the app's ID page. Enable the Associated Domains app service. Take note of your Prefix (bundle ID) and your ID (team ID) - you will need them later.

   

2. Add Associated Domain Capability to Your Application

   Add the "Associated Domain" capability to your app in Xcode, and add your web servers' domain as an associated domain.

   

3. Configure the Web Server

   • Create apple-app-site-association File

     Using the Prefix and ID from your app page, configure a JSON formatted file like the following and host it on an HTTPS web domain that is accessible from the root.

     For example, if you own the "https://www.mycompanywebsite.com/domain", your JSON file should be accessible at the URL "https://www.mycompanywebsite.com/apple-app-site-association". Note that the hosted file does not contain a .json file extension.

     {
       "applinks": {
         "apps": [],
         "details": [
           {
             "appID": "A4GXBZ4XU7.my.cool.app",
             "paths": [ "/page/all/", "/user/saved/*"]
           }
         ]
       }
     }

     The appID is your [teamID].[app bundle ID] and it identifies your app. The paths details valid content pages in your app. Apple recommends to keep paths short. Use a wildcard ("*") to specify all paths and use the "NOT" keyword to exclude paths, e.g. "NOT /user/saved/*". See Apple's documentation on enabling Universal Links for more information.

   • Handle Universal Links Code

     The final step is to make sure that any Universal Link that opens your app is handled correctly. To do so, implement the application:continueUserActivity:restorationHandler: method in your application delegate.

     - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler{
     if ([userActivity.activityType isEqualToString: NSUserActivityTypeBrowsingWeb]) {
     NSURL *url = userActivity.webpageURL;
     // Put code here to take user to relevant content
     }
     return YES;
     }

Singular takes care of this automatically. After you set up Universal Links for your iOS app, when you create a Singular Link for your app and enable deep-linking, that link will automatically function as an iOS Universal Link - providing both deep-linking and a mobile fallback.

Link Wrapping

Link wrapping, where another link redirects to the Universal Link URL, often causes deep-linking to fail (the user just gets taken to the mobile web page in their browser). This is because Apple wants “user intent” behind any rerouting, and a tracking link that redirects to another URL and results in deep-linking is not considered direct user intent. Therefore, you cannot use Universal Links with partners who link-wrap an attribution tracker’s tracking link.

To help understand and work around this industry-wide limitation, see our list of Best Practices and Examples.

Tracking Without a “Click”

If a user clicks on a tracking-enabled Universal Link, and it deep-links the user into the app (because the app is installed), some attribution trackers may not be able to track this touchpoint because the device did not perform any HTTP request and therefore no “click” is registered.

Using Singular takes care of this problem for you, as Singular Links ensures complete acquisition and re-engagement tracking of both install links and deep-links.