March 9th, 2016
As a deep linking company that handles millions of links every day, Branch deals with Universal Links on a daily basis. We see the vast potential, but are very familiar with its many problems. From being difficult to test, to inadequate edge case handling, to the sudden update that rendered URI schemes to ineffective, we understand that most developers have a rocky relationship with Universal Links. That’s why we’re excited to launch our open-source version of the Universal Links Validator, hopefully making every iOS developer’s life a little bit better.
Before we explain the tool, it’s important to first understand the basics about Universal Links. Universal Links is a deep linking standard made available by Apple in iOS 9. It allows users to be redirected to your app using paths from your website. For example, you could define a path in your apple-app-site-association file so that when users visit https://<yourdomain.com>/listings/*, they get routed to your app if the app is installed. Otherwise, Safari will take over and allow the http(s) link to load.
What makes the experience great for users is that they are routed directly to your App (bypassing Safari completely) when they have the app already installed.
The problem with this change is what happened to URI-based deep linking. If your team relied on URI schemes, Apple made a change in iOS 9.2 to make the ‘Open App’ modal a non-blocking modal. This means that URI schemes cannot be used to open the app directly from Safari from iOS 9.2 onward. Is this news to you? If so, we created a guide to transitioning from URI schemes to Universal Links just for you.
According to Apple, implementing Universal Links is a straightforward process. There are three steps you need to take. This may seem clear but it is a major pain point for developers and the number one source of support requests at Branch. As a result, we created a blog to walk you through the process of setting up Universal Links. Additionally, after hearing from hundreds of developers, we understand that troubleshooting Universal Links is anything but easy.
As app developers, we know how important it is that links route to your app and website correctly. We created Branch to solve the web-to-app routing problems at our previous mobile app startup, Kindred Prints.
If this is your first time setting up Universal Links, I highly recommend setting them up with Branch. Using Branch will save you a bunch of time because we abstract away steps one and two of Apple’s three-step process leaving you to simply configure your Xcode project and Apple Developer account.
To help with this onerous troubleshooting, I’d like to introduce Branch’s tool for validating your apple-app-site-association file. We call it the Universal Links Validator.
The first version of this tool was created by Graham, a previous Branch employee. He understood the pain that developers were going through when conforming to Apple’s requirements of hosting the apple-app-site-association. Our version of the tool is largely built on his open-source framework but takes a few more aspects of apple-app-site-association into consideration.
Branch’s Site Validator for Universal Links builds upon knowledge gained from troubleshooting various setups from Jack’s 51 iOS 9 Apps that Support Universal Links. If a Universal Link worked on our iOS 9.2 devices, we went back to the tool to understand whether the apple-app-site-association file validated correctly or not. If it didn’t, we tried to understand why and made the tool validate it. During the process, we learned a lot about apple-app-site-association file configurations for Universal Links.
As a result, the Universal Links Validator tool will test for the following when you type in your domain:
The original tool used validation rules that were more restrictive. Branch’s tool is different in the sense that the requirements for a successful validation of your apple-app-site-association file are closer to what we have found in production.
There are a few things we do not check for:
Also, our tool allows for many more content type headers on the file other than just application/pkcs7-mime (again this comes from production data).
Type your domain name into the Domain/Web Page box. It can also pick up the domain name from a Universal Link that you own. For example, if you type in: https://bnc.lt/Uldb/D99XFfuNVp it will strip out Uldb/D99XFfuNVp and return bnc.lt. The tool will then use bnc.lt as the domain for the rest of the validation steps.
If you encounter an error when the tool tries to test for compliance against the aforementioned rules, the tool will tell you what the error is.
If there are some tests that did not run due to a failure of a previous test, then those will be listed as well.
If all of your tests pass then your setup is most likely correct.
If all of your tests pass, we’ll also print your apple-app-site-association file.
That was a lot to cover! I would like to end by letting you know that we will be updating this tool quite frequently. As always, we’d love to hear your feedback. Feel free to drop us a line by contacting support if you think that there is a bug or simply have a feature request.
As a teaser, coming soon we’ll check whether your app is compliant with Google’s App Indexing requirements.