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.
What are Universal Links?
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.
Why Do I Need a Universal Links Validator?
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.
Developer Tool for Validating Your apple-app-site-association File
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:
- That your domain has valid DNS.
- That your apple-app-site-association file is served over https at the root of your domain i.e. https://<your-domain.com>/apple-app-site-association
- That your apple-app-site-association file’s ‘content-type’ header is set to one of the following MIME types:
- application/pkcs7-mime
- application/octet-stream
- application/json
- text/json
- text/plain
- The fact that your server does not return an error code greater than or equal to 400.
- That the content in your file can be parsed as JSON.
- That the JSON in your file has the appropriate paths entered.
- That the combination of your Apple-App-Prefix and Bundle Identifier that comprises the appId is available in the JSON file (optional).
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:
- The apple-app-site-association file being behind any sort of redirection scheme.
- The apple-app-site-association file being CMS signed by a valid TLS certificate.
- Whether your XCode project is set up correctly.
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).
How to Use the Site Validator
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.