Troubleshooting Universal Links for Non-App Developers
Published: 2024-01-04 22:51:50

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](https://developer.apple.com/documentation/xcode/supporting-associated-domains#Add-the-associated-domains-entitlement-to-your-app) while your website will need an [Apple App Site Association file](https://developer.apple.com/documentation/xcode/supporting-associated-domains#Add-the-associated-domain-file-to-your-website). 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](https://developer.apple.com/documentation/technotes/tn3155-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](https://replit.com/) 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](https://branch.io/resources/aasa-validator/)** - This validator from [Branch](https://www.branch.io/) 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](https://apps.apple.com/us/app/icarefone/id1156047132).

Hope these help save some time and frustration!