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. This file is also used for other purposes and setting this file up before Universal Links was quite cumbersome.
Before iOS 9, you were required to sign the apple-app-site-association
file with a valid SSL certificate and you had to include private keys; it just wasn't very easy to get started. In order to make Universal Links easier to adopt, Apple has removed this requirement. All you have to do now is create the apple-app-site-association
file and upload it to your server.
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": { "6AB81RGQLO.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 of 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, we have 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
.
Because Apple has dropped the complex requirement of signing your association file, this is all you need to do to prepare your server for Universal Links. It only takes a single configuration file that specifies your app and which paths on your website can be opened by your app.
If you have multiple apps that handle URLs for the same domain, you need to add multiple bundle ids to the details
dictionary. Make sure to prefix them with your team id and try to avoid any overlap between the paths your apps handle. If you do have overlap, there are no guarantees about the app that ends up handling the link and the experience could become quite confusing for you and your users.
Now that the server is ready to communicate to Apple that your app can open links for your site, let's stay on the server side a bit longer. Let's have a look at Smart App Banners and how you can optimize your html to add the most value to your app.