Preparing your server for Universal Links

Setting up Universal Links on the server side has been made as straightforward as possible by Apple. All you have to do is host a file on your own server that can prove the connection between your app and your server. This is done through a file called the apple-app-site-association file.

The apple-app-site-association file contains a dictionary of information that describes exactly how your app is tied to your site. Let's have a look at an example of an apple-app-site-association file. The example describes the implementation for a recipe app where users can simply browse and search recipes for food:

{ 
    "applinks": { 
        "apps": [], 
        "details": { 
            "6QA73RGQR2.com.donny.recipes": { 
                "paths": [ 
                    "/recipes/*/", 
                    "/search/" 
                ] 
            } 
        } 
    } 
} 

Let's go over this configuration file bit by bit. Firstly, we need to create some mandatory dictionary keys. The applinks key tells Apple that this part of our association applies to Universal Links. Inside this key, we define an empty apps array that we don't need to put anything in and then we have the details key. The details key is a dictionary that contains our configuration.

First of all, your app identifier should be added as a key for the details dictionary. The prefix you see in front of the app identifier is your team identifier. You can find your team identifier in the Apple Developer portal.

Finally, there is a paths array inside the dictionary that's associated to our bundle identifier key. This array specifies all the paths on our website that we want to handle. Imagine that our website's base URL is https://www.donnysrecipes.com/. For this URL, https:// is the scheme, www.donnysrecipes.com is the domain, and anything after the trailing / is called the path.

The example configuration handles the /recipes/*/ and the /search/ paths. The * in /recipes/*/ means that we're matching on a wildcard. In other words, we specify that our app is able to open URLs such as https://www.donnysrecipes.com/recipes/10/, https://www.donnysrecipes.com/recipes/20/, or any other URL that looks similar.

The /search/ path is a bit more interesting. We didn't specify a wildcard anywhere, yet our app will be able to handle URLs such as https://www.donnysrecipes.com/search/?q=macaroni. That final segment, ?q=macaroni, is called the query string and we don't need to specify that we match on that because it's not part of the path.

Once you have created and configured your apple-app-site-association file you need to upload it to your server. It's important that you host the association file in a way that makes it accessible on a URL similar to https://www.donnysrecipes.com/apple-app-site-association. In other words, the path to this verification file on your server should be /apple-app-site-association.

Now that the server is ready to communicate to Apple that your app can open links for your site, it's time to see how you can set up your app to handle Universal Links.