Universal Links promise to simplify deep linking on iOS and do partially deliver on that promise, but they’re not without their issues. Notably, there are lots of edge cases where they don’t work as you might expect and can be flaky, especially during development.
This post walks you through what to do if you’ve set up Universal Links, but they don’t seem to be working. If you’re looking to set up Universal Links, follow our iOS Deep Linking with Universal Links Setup Guide.
Are you on an iOS simulator?
Use a device. Universal Links won’t work at all on the iOS simulator. Fun, right?
Are you on an iOS 9 device?
Universal Links won’t work before iOS 9. This seems obvious but is easier to do than it sounds.
Did you prepend the domain with applinks: in your Associated Domains entitlement?
Each domain that you want to use for Universal Links must be listed in the Associated Domains in the format applinks:mydomain.com.
Are you correctly hosting a valid Site Association File?
There must be a valid Site Association file served over SSL at the URL: https://mydomain.com/apple-app-site-association.
Apple provides a tool to validate that this file is accessible and valid: Universal Links Validation Tool.
Are you using the www. subdomain?
www.yourdomin.com and yourdomain.com are two different domains. Ensure that you’re consistently using one or the other accross the hosting URL for the Site Association File and Associated Domains entitlement configuration.
Are you blocking access to your Site Association File?
The robots.txt file for the Universal Links domain must allow access to the Site Association File in order for iOS to crawl it to verify the trust relationship.
Does your Site Association File contain your full bundle identifier and Team prefix?
Your appID in the Site Association File must follow the format TEAM-PREFIX.com.myco.appname.
Your Team Prefix is an ID for your Team in the Apple Developer Center that you very rarely see. You can get it here.
What should a valid Site Association File look like?
The most basic site association file looks like this…
{
applinks: {
apps: [ ],
details: [
{
appID: "TEAM-PREFIX.com.myco.appname",
paths: [
"*"
]
}
]
}
}Is the iOS Site Association Cache hurting you?
iOS caches Universal Links domain -> app associations and refreshes them periodically. It will always refresh the assocation and re-fetch the Site Association File when the app is re-installed freshly.
Have you disabled Universal Links for your domain?
Tapping the top-right ‘yourdomain.com >’ button in the status bar from your app will open the Universal Link in safari, but will also cause iOS to open all future links for that domain in Safari too (essentially disabling Universal Links.) In order to re-enable Universal Links, open a URL on your domain that supports Universal Links and tap the ‘Open’ button in the bar that appears at the top of the page.
Still not working? Try the device log
Universal Links (or rather the Shared Web Credentials Daemon) logs a lot of useful information to the Device Log.
- Connect your device to a computer running Xcode
- Open the Devices window and choose your device
- Install the app while watching the log
You can filter for swcd for only those events from the Shared Web Credentials Daemon – this will often give you a hint as to what’s not working.
Thanks to @iterrell for this tip.
Other common issues?
Let us know if we’ve missed something and we’ll add it here!