App Linking

Want to learn how to increase app engagement with universal links? In this tutorial we will review the end-to-end steps to get your Web server and app setup for app linking. From a user perspective app linking is as simple as tapping a link (see figure 1). Universal links will be routed to the app when the link has been enabled for app linking and the app is installed. However, if the app is not installed, the link will naturally open in the default browser.

Figure 1. App linking workflow

Get your server ready

The first task for enabling app linking is to configure the links or paths that should be associated to your app. This configuration is setup with the apple-app-site-association file that is deployed to the root of your HTTPS Web server.

Create the Apple association file

Create the apple-app-site-association JSON file with Apple's recommended format. This file identifies the paths or links that are linkable for your app. You may setup your path mappings to be specific or wildcard matchers. For example, the example below (see Listing 1) will route all links to your app via a wildcard path matcher. The appID key is the team ID or app ID prefix, followed by the bundle ID.

Listing 1. Creating an apple-app-site-association file

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "{team-id-OR-app-prefix}.{app-bundle-identifier}",
                "paths": [ "*" ]
            }
        ]
    }
}

Upload the apple-app-site-association to the root of your Apache server or in the .well-known subdirectory. The default Apache server root exists at /Library/WebServer/Documents.

Configure the association file

The MIME type for the apple-app-site-association file must be application/json. This can be configured in Apache's httpd.conf file (see Listing 2).

Listing 2. Configure MIME type for apple-app-site-association file

<Directory "/Library/WebServer/Documents">
....

#
# Setup MIME type for Apple association file
#
<files apple-app-site-association>
Header set Content-type "application/json"
</files>
</directory>

Test the association file

Start your local Apache Web server via the Terminal:

$ sudo apachectl restart

Verify it is running at http://localhost. Next, setup your local Web server for SSL. Apple requires the association file to be deployed to an HTTPS Web server. The simplest way to deploy your localhost as a publicly accessible Web server via HTTPS is with ngrok. After downloading ngrok run the following command via Terminal (see Listing 3).

Listing 3. Starting ngrok

$ ./ngrok http 80

Tunnel Status                 online                                            
Version                       2.0.25/2.0.25                                     
Region                        United States (us)                                
Web Interface                 http://127.0.0.1:4040                             
Forwarding                    http://b5bdc858.ngrok.io -> localhost:80          
Forwarding                    https://b5bdc858.ngrok.io -> localhost:80  

The prior command to start ngrok (see Listing 3) assumes ngrok is installed at the root directory and localhost is running at port 80. Copy the HTTPS generated URL from ngrok (See Listing 3, line 8) and test it from a browser. Congrats, your localhost is now publicly accessible over HTTPS! This is also the HTTPS URL our iOS app will be associated with when testing locally.

Next, verify the MIME type for the association file is correctly configured with a content-type of application/json in Terminal (see Listing 4).

Listing 4. Verify MIME type

$ curl -I "https://b5bdc858.ngrok.io/apple-app-site-association"

HTTP/1.1 200 OK
Date: Sat, 07 May 2016 12:50:44 GMT
Server: Apache/2.4.18 (Unix) PHP/5.5.31
Last-Modified: Mon, 04 Apr 2016 12:06:48 GMT
ETag: "c9-52fa79025e600"
Accept-Ranges: bytes
Content-Length: 201
Content-type: application/json

Our last test is to verify our domain with Branch's Universal Links Validator. Copy your HTTPS URL and run it against their validator (see Figure 2).

Figure 2. Universal link validator

Get your app ready

The final task is to enable our app for universal links and setup the code to intercept and manage link validation and routing.

Enable Associated Domains in Xcode

In Xcode, navigate to your target's Capabilities tab and toggle Associated Domains on. Then, add each domain which hosts the corresponding association file and prefix it with applinks: (see Figure 3).

Figure 3. Enable associated domains

Update App Delegate

Add a new AppDelegate+AppLinking.swift file with the following code to handle universal link validation and routing. This code simply prints the URL of the universal link and by default forwards to the initial view controller. Refer to Apple's WWDC video on App Linking for validation and routing best practices.

import UIKit

extension AppDelegate {
    
    func application(application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
        
        if let url = userActivity.webpageURL where userActivity.activityType == NSUserActivityTypeBrowsingWeb {
            print("url=\(url)")
        }
        
        return true
    }
    
}

Testing App Linking

After installing the app on a device, paste the HTTPS URL for your website as a link in any iOS app (Mail, Messages, Contacts, etc.) and click the URL (see Figure 1). Did the link take you to your app? If yes, congratulations! You have successfully setup app linking. If you encounter any issues refer to my tips below. After a successful test remove the installed app and re-test the link. Without the app installed the link behaves like an ordinary link and forwards to the website (see Figure 1).

Tips

• The apple-app-site-association file must not have a .json extension.

• App link testing will only work from an actual device. Testing from a simulator will not work.

• The instructions provided above are for iOS 9 and above. If you need to support iOS 8 you are required to sign the apple-app-site-association file. For additional information on iOS 8 support refer to Apple's note on iOS 8 support. Fortunately, certificate signing is not required on iOS 9 and above when the association file is deployed to an HTTPS server.

• App linking only works when clicking a link from within an Apple app (Mail, Messages, Contacts, etc). App linking will fail from third party apps like Gmail, Facebook, etc.

• For additional information on App Linking refer to Apple's documentation or their WWDC talk on App Linking.