How to enable Universal Links in iOS 9+

Apple’s documentation states that “Adding support for universal links is easy. There are three steps you need to take”.  However, there is much more to it than that.  Here is what you really need to do.

apple-app-site-association file

Create the apple-app-site-association file and place it at the root of your webserver or the .well-known subdirectory.

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "9JA89QQLNQ.com.apple.wwdc",
                "paths": [ "/wwdc/news/", "/videos/wwdc/2015/*"]
            },
            {
                "appID": "ABCD1234.com.apple.wwdc",
                "paths": [ "*" ]
            }
        ]
    }
}

The appId is your App Prefix or Team Id followed by the Bundle ID. You can get this from https://developer.apple.com/account/#/membership/ and look for the Team ID value.

If your server doesn’t already have an SSL certificate you’ll need to obtain an SSL certificate and set up https.  You can obtain an SSL certificate from https://www.namecheap.com.  They are a reseller of Comodo, RapidSSL,  GeoTrust, and Thawte certificates.  You can get it cheaper through namecheap than buying directly.  Follow their instructions to generate a certificate signing request and validate it.

Next you need to enable SSL on your webserver.  Place your certificates and private key somewhere on your server such as /etc/apache2/ssl and enable read-only access to root

sudo chmod 400 ./*

If you have Apache2 go to /etc/apache2/sites-available and edit the default-ssl.conf file.  Set the following lines to the correct values for your server:

ServerName yourservername.com
ServerAlias www.yourservername.com
ServerAdmin [email protected]
SSLCertificateFile /etc/apache2/ssl/yourservername_com.crt
SSLCertificateKeyFile /etc/apache2/ssl/yourservername.key
SSLCACertificateFile /etc/apache2/yourservername_com.ca-bundle

You’ll also have to tell your webserver to set the header of the apple-app-site-association file to application/json.

Add the following Files tag to your default-ssl.conf file:

<Files apple-app-site-association>
        Header set Content-Type "application/json"
    </Files>

If you have ubuntu you will need to run the following three commands as well to turn on ssl and enable the headers.

a2enmod ssl
a2ensite default-ssl.conf
a2enmod headers

Check that your syntax is correct by running:

apachectl configtest

Lastly restart the server to apply your changes with:

service apache2 restart

You can test that your server is configured properly via this online tool: https://branch.io/resources/universal-links/

Configure your app

Via Xcode, select your project’s target.  Go to the Capabilities tab and enable Associated Domains.  Add each of your domains with:

applinks:yourservername.com

Go to https://developer.apple.com/account/ios/identifier/bundle and select your app.  Edit its capabilities here to enable Associated Domains.  This will invalidate your existing distribution profile, so you’ll have to create a new one of those as well.

In your AppDelegate file add support for  application:continueUserActivity:restorationHandler:

Apple documentation

Did you find this post helpful? Support independent development and improve your sleep by downloading White Noise and Deep Sleep Sounds free from the App Store.