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.

General Gotchas

• 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.com in 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-association file 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 https://app-site-association.cdn-apple.com/a/v1/yourdomain.com.
• The Apple docs claim you can bypass the CDN by adding ?mode=developer to 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.)

Tools

AASA Validator | Branch - This validator from Branch will run a set of 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 content-type header.

Potential Gotchas

• 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-association file 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-association file. 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.

Potential Gotchas

• This isn’t swcutil specific 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 found error.

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.

Potential Gotchas

• 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!