Using Sysdiagnose on iOS to Troubleshoot Universal Links

Dealing with universal links on iOS can sometimes be tricky, especially when something goes wrong. There are a lot of details in configuration, and stepping through all of it to debug can be difficult.

I myself ran into an issue with universal links on an app recently. For some reason, the links kept opening up in a web browser instead of going to the app, almost like the device wasn't able to find the apple-app-site-association file associated with the domain. This is the file that iOS looks for whenever it installs an application, to make sure it knows how to route universal links (among other things). You can find more documentation on how they're set up in the Apple documentation.

But I was at an impasse. Everything I was looking at was telling me that the universal links should be working, but they weren't. But I couldn't figure out how to make sure the device was properly downloading and parsing the apple-app-site-association file, which was the last piece of the puzzle.

...or could I?

Let's troubleshoot.

It turns out, there's a way to get a large archive of system diagnostics information from any iOS device. And one of the things in those system diagnostics is how apps are configured for universal links and will let you know things like associated domains, parsed paths and so on. Apple has a document on how to do this, but I also want to step through it here.

If you go into Settings, then into Accessibility, then into Touch and then into AssistiveTouch, you can discover a plethora of options.

Turning on AssistiveTouch provides a software home button that has extremely configurable functionality. This is a really cool accessibility feature in and of itself, especially if you find it difficult to do some of the system gestures or you can't interact with the physical buttons. You can learn more from Apple support, and I really suggest checking it out. Unfortunately, this software home button doesn't show up in screenshots, so you'll have to turn it on yourself to see it.

For the purpose of this article, one of the things you can do with the AssistiveTouch button is to generate those system diagnostics — this is the option "Analytics" under "Custom Actions." You can see that I've already done this for the Double-Tap in the screenshot above.

Now, if you double-tap that button, a little notification at the top shows up to tell you that the device is generating diagnostics.

It takes a while for this process to finish — up to ten minutes — but it will show you another notification when it's done.

To get those logs off of the device is a bit more tricky since it can weigh in at hundreds of megabytes, so it can't be sent by most conventional methods. You can go take a look at it in Settings, if you go to Privacy, then Analytics & Improvements, then Analytics Data. This is where you can see all of the analytics data collected and stored by the device, and if you scroll down you can eventually find the sysdiagnose file.

If you select this, you get a blank screen with a share icon in the corner.

One way to get this file off of the device is via AirDrop: select the icon, select AirDrop and select your target computer. Remember that this puts it into your Downloads folder. Alternatively, you can use a program like iMazing to pull the file from your device's filesystem.

Then you can unzip it.

There are a lot of files in this archive! I haven't even begun to scratch the surface of useful information you can find here; for now, I'm going to look just at the swcutil_show.txt file. If you open it up and take a look, you can see how it's useful.

Viewing the "Database" section, we can see that every app on the device that has entries in an apple-app-site-association file shows up here, along with what URL it got the file from and how it parsed it. For example in the screenshot above, you can see that the Wallet app is associated with the domain wallet.apple.com and has several patterns in that domain that will link to the Wallet app.

With the information in this file in hand, I was able to identify what the gap was — I had structured my site association file wrong — and solved the issue. Hooray!

So if you're having issues with your universal links or anything else in the apple-app-site-association file, I suggest going through this process to get a diagnosis to help you debug your problems faster.