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 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 illustrates the implementation for a recipe app where users can browse and search recipes:

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

Let's go over this configuration file bit by bit. Firstly, some mandatory dictionary keys are set up. The applinks key tells Apple that this part of the association file applies to Universal Links. Inside this key, an empty apps array is defined. This array does not need to have any content in it for a simple integration. The details key is a dictionary that contains the actual configuration.

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.

There is also a paths array inside the dictionary that's associated to the bundle identifier key. This array specifies all the paths on our website that your app should handle. Imagine that your 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 /search/ paths. The * in /recipes/*/ represents a wildcard value that could be anything. In other words, the config is set up to handle 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. No wildcard values were specified for this path, yet the app will be able to handle URLs such as https://www.donnysrecipes.com/search/?q=macaroni. That final part in the URL, ?q=macaroni, is called the query string and you don't need to specify that you want to 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.