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.
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 fileCreate the
apple-app-site-associationJSON 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
appIDkey is the team ID or app ID prefix, followed by the bundle ID. Upload the
apple-app-site-associationto 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 fileThe MIME type for the
apple-app-site-associationfile must be
application/json. This can be configured in Apache's httpd.conf file (see Listing 2).
Test the association fileStart your local Apache Web server via the Terminal:
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).
$ sudo apachectl restart
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).
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).
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).
Update App DelegateAdd a new
AppDelegate+AppLinking.swiftfile with the following code (see Listing 5) 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.
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).
apple-app-site-associationfile 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-associationfile. 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.