Solving Troubleshooting: A New Universal Link Validator

Getting users inside of your app is the most important part of a deep link, and if your links don’t open the app, it can severely hurt the user experience. Apple’s introduction of Universal Links in iOS 9 provided a new way to directly open your app, without having to rely on URI Schemes redirecting through Safari. At the surface level, Universal Links seem pretty straight forward: Host a file on your website, and add your website domain to the Xcode project. However, while Universal Links certainly have their advantages, they are far from perfect. While Universal Linking creates a more elegant user experience, they also introduce additional configuration complexity.  

The Difficulty of Troubleshooting Universal Links

Universal Links require that both the website and the app be in agreement that a link should launch your app. Apple maintains that Universal Links setup is an easy, three step process:

1. Create an apple-app-site-association file that contains JSON data about the URLs that your app can handle.
2. Upload the apple-app-site-association file to your HTTP(S) web server. You can place the file at the root of your server or in the .well-known subdirectory.
3. Prepare your app to handle universal links.

Unfortunately, it’s a little more complex than that. From the issues with conforming to Apple’s AASA file requirements, to setting up your Xcode project, Universal Links can be a major pain point for developers.

Branch exists to make deep linking into mobile apps as easy as possible, from every step between setup and release. When Universal Links were first released, this meant that Branch would automatically set up and fill in the values for your AASA file. We even released a developer tool that allowed you to check that your AASA file was correctly set up. However, while this took care of steps one and two of Apple’s setup process, it left developers struggling with setting up their Xcode project. Today, we’re excited to introduce a tool to solve step three of setup: the new Universal Linking Validator.

Automated Validation for Your Xcode Project

Part of the beauty of our AASA Validation tool was that it was absolute, with no guess work involved: you entered your domain, and if something was wrong, the tool told you exactly what it was. The new Universal Links validator similarly examines your project, and if it finds an issue, it will tell you exactly what needs to be done to fix it. When run, the validator will check that:

1. You have enabled Universal Links on the Branch dashboard
2. The Bundle Identifier of your project has been correctly entered on the dashboard
3. The project’s team id matches the Apple App Prefix entered on the Branch dashboard
4. The .entitlements file has the correct build target selected
5. The .entitlements file contains your Branch domain, and that the entry is correctly formatted

The validator will also check your URI scheme settings, to make sure your app will be opened in every scenario.

With this tool, you can spend less time troubleshooting Universal Links, and more time creating a great deep linking experience for your users.

Checking Your Own Project

With all the complications of setting up Universal Links, we wanted to make sure that troubleshooting them was a simple one. The Universal Links Validator works in two parts, a locally run bash script that checks your project, and a web app for viewing the results. To start the validation process, download a copy of the local script, and open a terminal window. To check your project:

1. Type bash into the terminal
2. Drag and drop the script, and then your .xcodeproj file into the terminal
3. Hit enter

The script will do the rest: