DEV Community

Lauren Ashpole
Lauren Ashpole

Posted on • Originally published at blog.laurenashpole.com

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!

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Explore a sea of insights with this enlightening post, highly esteemed within the nurturing DEV Community. Coders of all stripes are invited to participate and contribute to our shared knowledge.

Expressing gratitude with a simple "thank you" can make a big impact. Leave your thanks in the comments!

On DEV, exchanging ideas smooths our way and strengthens our community bonds. Found this useful? A quick note of thanks to the author can mean a lot.

Okay