So, you’ve followed all the steps to enable Universal Links for your app, but somehow, the links still fail to open your app? This blog aims to cover exactly where and how to fix these issues. (If you are still learning about Universal Links and trying to set them up, I’d suggest you read this post first.)
Troubleshooting Universal Links
Universal Links can be tricky. So let’s do a quick diagnostic test on your setup:
1. Check if your applinks are registered with iOS as Universal Links:
Paste the link on the Notes app and long press it. If you see an option to Open in <<App Name>>, then it suggests that Universal Links were disabled for your domain name. Use the Open in <<App Name>> option to open the app. This will re-enable Universal Links for your domain. If you don’t see the option to Open in <<App Name>>, then it suggests that there is some error with the association that iOS makes between the domain and the app.
2. Check AASA file:
You need to first check if your AASA file is hosted on your domain and is getting served properly. If you are using Branch Universal Links, this step is not required as Branch takes care of serving a valid AASA file. However, if you are using your own hosted AASA file, you can use AASA file validator found here.
If your AASA file looks good, try to delete and reinstall the app. This will prompt iOS to re-scrape the AASA file. Then check whether applinks are registered with iOS using the steps from Step 1.
3. Check Associated Domains entry in your entitlements file:
Go to the Capabilities tab of your project file in Xcode and scroll down to Associated Domains. Ensure that associated domains are added in the form:applinks:<<yourdomainname>>*Note that this domain name needs to be the one where your AASA file is hosted.
If you see an error while adding the associated domains, please ensure that the right team is selected for your Xcode project and that the Bundle Identifier of your Xcode project matches the one used to register the App Identifier with Apple.
If there was an error with either of the above settings, please rectify that, delete the app on the test device, deploy a new build and test with steps in Step 1.
Some other things to keep an eye out for when dealing with Universal Links:
Universal links can be disabled
Yes, Universal Links can get disabled. When the user is deep-linked into an app via a Universal Link, iOS display a forward arrow button to the domain name at the top right of the screen. If the user inadvertently taps that, iOS will disable Universal Links for that domain-app pair. To re-enable Universal Links, user would have to long tap the link and select Open in <<appname>> option as detailed out in troubleshooting Step 1 above.
Universal Links do not work on Javascript redirects
For better or for worse, you cannot redirect to a link and expect it to open the app on iOS. Universal Links are designed to work on user intent and will not deep link if wrapped inside another domain that redirects to the associated domain.
Many apps don’t support Universal Links.
Universal Links are not yet supported on a lot of apps. If you are clicking the link from say Instagram, Twitter or Facebook, don’t expect the link to directly open your app. However, they do work from apps like Notes, iMessage, Slack, Whatsapp etc. Here is a detailed list that we continually update, along with info for how you can make them work on some unsupported apps.
If you are using Branch Universal Links, our integrations team, which gets tons of queries around Universal Links, has built a tool to validate Universal Links in your Xcode project. It can be found here and is pretty nifty when it comes to troubleshooting Universal Links.
If you aren’t using Branch Universal Links, now’s as good a time as any to request a Branch demo or to get started!