iOS's Universal Link is an useful technology linking URL between websites and native apps. When it works, it works like magic.🧞♂️
But when an Universal Link is not working, debugging on it is also like debugging magic.🤦♀️
Sometimes it just don't work🤷♀️
Developer need to check their website has the
apple-app-site-association file setup correctly, and check the app's associated domain setting.
You can use the App Search API Validation Tool to check the association files, but an on device checking tool is better for integration test. I've developed an app tool—Knil, for testing Universal Links on the device.
If both the website and the app seems to setup correctly, there might be something wrong in the system.
As you can see, there are some radars related to iOS failed to download Universal Link's association files:
- rdar://33893852 Certain users fail to download apple-app-site-association when downloading the app
- rdar://45201697 iOS 12 cannot fetch AASA file within 5 minutes after rebooting the phone
According to the spec, the association file should be downloaded every time the app installed, updated, or reinstalled. But this process is in the background, how can we check if iOS really download the files?
Logs from Console
We can use device Console to see some logs.
Open Xcode. In the menu bar, select Window ➡️ Devices and Simulators, select a connected device, and tap Open Console.
In the search field, we can then filter the logs with keyword
These logs provide some activities related to Universal Links and other associated domain features. We can see the system are doing something, but not much detailed information. The hostname even got redacted. So overall it's not very helpful.
Logs from sysdiagnose on iOS 13
Fortunately, new in iOS 13, there will be logs of Universal Links in sysdiagnose. You are looking for the file named
If you are not sure how to collect sysdiagnose, follow the instructions on the developer website.
swcutil_show.txt file, we will see a lot of data iOS collected from the association files, and the dates it collected:
- App ID
- App Version (build number)
- Last checked date
- Next check date
With these information we can check whether the system caches the data we want it to, or at the time we expect. We can install or update the app and compare the dates.
If you are debugging Handoff or iCloud Shared Web Credentials, the file also contains logs of activitycontinuation and webcredentials.
Although sometimes Universal Link still might not work as expected, at least we now have a much clear picture of the system behavior.🤗
If there are still problems, filing Feedbacks to Apple with detailed information is also easier thanks to iOS 13's Feedback Assistant app collects sysdiagnose automatically.