How to set up iOS 9 Universal Links (deep linking) for your app

Much has been written already about iOS 9’s new features.

Before iOS 9, the mechanism to open apps which were installed was to open Safari, try to open a deep link and use a timer fallback to the App Store.

On iOS 9, Apple announced “Universal Links” where instead of opening Safari first, the iOS will check if the Universal Link is registered to the domain associated with the link, then checks if the corresponding app is installed. The app is opened if installed, and if not, Safari will be load an http(s) link. This functionality allows one link for both website and app.

The idea behind Universal Links is to use the same link for both your app and website while seamlessly being redirected to your installed app without going through the Safari browser. 

In order to support Universal Links, you need to setup both your app and your website so iOS can establish a trust between them.

Deep linking – how it works:

When the app is installed or updated, iOS will check which websites are acceptable by this app as Universal Links.

It will then check each of these websites to verify the app is registered there.

This is done by placing a file with the app IDs on the website and a list of domains on the app.

Preparing your website:

Note: AppsFlyer customers do not need to add any code to their website.

First you should create an apple-app-site-association file (Note: that there’s no .json file type).

Then you can place the apple-app-site-association file and identify app IDs and paths on your website. You can define several apps in this file and iOS will follow the app order when looking for a match so you can specify different apps to handle different paths on your website.

Here’s an example of the apple-app-site-association file:

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "9JA89QQLNQ.com.my.bundle.id",
                "paths": [ "/myPath1", "/myPath2/*" ]
            },
            {
                "appID": "TeamID.BundleID2",
                "paths": [ "*" ]
            }
        ]
    }

}

The “apps” key in the apple-app-site-association file must be present and its value must be an empty array.

The value of the “appID” key is the team ID and the bundle ID joined with a period. The team ID appears on Organization Profile > Account Summary on Apple’s Developer Portal.

When you enter the Member Center on http://developer.apple.com, click you name on the top right and select “View Account”:

The Team ID appears on the Developer Account Summary section:

Once you’ve done the above, you can upload the apple-app-site-association file in the root of your HTTPS web server.

The file should be accessible without redirects at http:///apple-app-site-association

Guide

Everything a developer needs to know about deep linking

Learn more

Preparing your app

Creating provisioning profile

Assuming your app is already registered on Apple’s Developer Center, you will need to enable “Associated Domains” on your app’s Identifier.

Go to Identifier->App IDs, select your app and enable “Associate Domains”:

Next, you need to generate your provisioning files for your app, download them and double click to install them on Xcode.

Go to Xcode and select your app target. On the Capabilities section, enable “Associate Domains” and add each of the domains supported by your app.

You have to prefix each domain with “applinks:” (for example: applinks:domain.com) and also add any sub domain that you want to use with Universal Links.

To handle the link inside your app when it is opened by Universal Link just implement application:continueUserActivity:restorationHandler: on your AppDelegate.

if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
       NSURL *url = userActivity.webpageURL;
       // do something with the URL
   }
  
   return true;
}

Now that your app and website are setup all you have left is to test it.

Load an HTTPS link which is configured as described above. If your app is installed it should open the app, otherwise it should open the website.

Get the latest marketing news and expert insights delivered to your inbox

Troubleshooting

1. Note that Gmail and Google Inbox apps do not handle Universal Links properly (they will not open the apps). It’s not possible to open any app by any universal link in there apps.
2. When the app is installed and an associate domain defined in the app does not response, iOS will show an error on the device log. However, it will not show anything in case of success.
3. If the provisioning file is not updated from the Apple developer center, the associate domain will not be processed and the Universal Links setting of the app will be ignored. This applies both to the development &App Store provisioning files.

Looking Forward

It will be interesting to see how Apple evolves this technology in the next iOS release.

In the meantime, you can learn more about how our OneLink solution makes deep linking easier on iOS 9, and we hope you found this post helpful. Please look for future posts addressing the technical challenges of the mobile industry.