Troubleshooting Universal Links for Non-App Developers
Universal links are Apple's way of directing a link to an app (if installed) or website. Setting them up requires updates to both your app and website. On the app side, you'll need to add your site's domain to the associated domain entitlements while your website will need an Apple App Site Association file. If, like me, you've exclusively done web work, some of the documentation and tools may feel a little dense or unfamiliar. For example, Apple's technotes on Debugging Universal Links is a great resource but assumes some prerequisite app development knowledge. So, this is a guide for troubleshooting universal links designed specifically for people without that experience.
- Links will only open in app when tapped; they cannot be copied and pasted into the URL bar.
- The link can't be rendered on the domain you added to the app's associated domains. So basically, if you want to open a link to
https://yourdomain.comin app, the link shouldn't be on the page
https://yourdomain.com/test-universal-links. As a workaround, I used Replit to publish quick pages to share on mobile. You can also paste links into your Notes app for personal testing.
- Instead of pulling the
apple-app-site-associationfile directly from your web server, Apple will serve it from their own CDN. I generally saw updates in about a day but your mileage may vary. If you want to check their cache, you should be able to hit
- The Apple docs claim you can bypass the CDN by adding
?mode=developerto the app's associated domains. However, in my experience, backed up by a few users in the Developer Forums, including the param broke universal linking entirely. (It's very possible that I just missed a step so, if you know what I did wrong, please let me know in the comments.)
AASA Validator | Branch - This validator will run a few checks on your
apple-app-site-association file but it's especially reassuring to know that the file contains valid JSON and includes the correct
- The file Branch validates comes from your web server so it may not match what Apple has saved in its CDN.
swcutil - swcutil is a command line tool that comes built-in on a Mac. You can run
swcutil -h to view a list of options but the ones I found most helpful were:
swcutil dl -d yourdomain.com- View the contents of an
apple-app-site-associationfile from a specific domain.
swcutil verify -d yourdomain.com -j ./apple-app-site-association.json -u https://yourdomain.com/page- Verify that a URL matches a pattern in an
apple-app-site-associationfile. This checks against a JSON file on your computer (see the second parameter) so make sure to download it and point to the correct location.
- This isn't
swcutilspecific but, if you're testing a link with a query parameter, make sure to escape the question mark or you'll get a
zsh: no matches founderror.
iPhone Developer - If you have the app installed on an iPhone, you should be able to use the Universal Links Diagnostics option in Settings > Developer. Enter a URL and the tool will check whether that page would open in an installed app. It also provides the app ID.
- To use the Developer tools, you'll need to enable Developer Mode on your iPhone and that's trickier than expected. The toggle switch should be under Settings > Privacy & Security but it doesn't appear by default. To see the switch, you'll need to connect your phone to your computer and either a) open a project in Xcode or b) use a program like iCareFone.
Hope these help save some time and frustration!