3Min. Read 91Shares

How to Set Up iOS 9 Universal Links (Deeplinking) for Your App

Gil Meroz Oct 20, 2015

Much has been written already about iOS 9’s new features. In fact, we published a post about ways it will impact mobile marketers. This post is meant for a technical audience and addresses Apple’s new deeplinking protocol.

Before iOS 9 — the mechanism to open apps which were installed was to open Safari, try to open a deeplink 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.

Deeplinking – 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. Learn more about our OneLink solutions for iOS 9 here.

  1. Create a apple-app-site-association file. Note that there’s no .json file type
  2. 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”:

ViewAccount

The Team ID appears on the Developer Account Summary section:

teamid

3. Upload the apple-app-site-association file in the root of your HTTPS web server. The file should be accessible without redirects at http://<domain>/apple-app-site-association

Preparing your App

Creating provisioning profile
1. 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”:

AppID

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

Configuring your app

3. 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.

xcode

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;

}

Testing
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.

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 deeplinking 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.

Comments