🔗 Troubleshooting Universal Links (aka Deep Links) in iOS
Your one-stop shop for the most common Universal Link issues in iOS. Troubleshooting your deep links starts here!
Over the course of years, I worked closely with deep links, facing many different issues. Some of those issues were reported repeatedly as they could be sometimes user error, or lack of support in certain 3rd party apps. As I learned from these mistakes, I put together this page with links to articles and documentation that helped me solve common setup issues and also recurring ones — even when the issue could be tied to a user’s device specifically.
The links below are mostly from Branch and AppsFlyer, two of the most popular deep link providers, but that doesn’t mean that each resource applies only to their respective services or SDKs. In fact, most of them are independent of the service and apply to deep links in iOS in general, while some even apply to Android deep links as well.
Disclaimer: for the purpose of keeping the lingo simple, I’ll use “Universal Link” and “deep link” interchangeably in this article. Universal Links are Apple’s brand name for what’s popularly known as “deep links”, while Google calls theirs “App Links”. Deep links can also be interpreted as those app-specific URL schemes like “
whatsapp://”, but popularly most people generalize and call those, as well as Universal Links and App Links as simply “deep links”.
Troubleshooting Deep Link Issues
Branch - iOS Troubleshooting: Must-read resource on how to solve common deep link issues (Branch-specific, or not). Contains potential solutions to problems that include (but are not limited to):
App not opening when using deep link.
App not passing data when using deep link.
Deferred deep linking not working.
How to re-enable Apple Universal Links.
Determining if deep link is from Branch or not (without network connection).
Explains how Universal Links work.
Lists examples of known apps that might not support deep links very well, e.g. Chrome, Facebook, WeChat, Twitter, LinkedIn, Instagram, Pinterest, etc.
Contains other valuable troubleshooting FAQ that are not included elsewhere.
Explains great examples of why your deep links might not be opening the app. Definitely a must-read.
Example specific to Branch on how to view deep link data: simply add
?debug=1to the end of your deep link. (Works for Branch’s deep links only)
roger.ml is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.
AppsFlyer - OneLink troubleshooting and FAQ: This is a great resource for troubleshooting OneLink issues, including (but not limited) to answering these questions:
Deep Link Developer Documentation
Has a super helpful visual diagram of how deep linking works on iOS, and explains some implementation details.
Explains how Ad Links should be created.
Thorough guide explaining how to integrate Branch's Universal Email solution with your Email Service Provider (ESP).
If you're using Iterable as your ESP, a must-read is Iterable - Deep Links Setup.
Understanding Deep Links Concepts
Explains how SKAdNetwork works, in particular with Branch.
Contains lots of helpful tables and a visual diagram of how SKAdNetwork works.
An extensive glossary on common terms used around the industry, engineers, and marketers.
A mobile marketing glossary featuring must-know industry terms, topics, and concepts to help you keep up.
App Tracking Transparency Prompts
When the subject is deep links, we’re often associating them with ad attribution, thus, App Tracking Transparency requests. I found this very useful resource that shows examples of prompts that other apps are using in the wild. Definitely worth checking out if you show this prompt to users:
Status Pages of Deep Link Services
Sometimes Branch and AppsFlyer go down. This causes issues creating deep links (which would impact your BE if you’re creating them through their API), resolving deep links (or their parameters) in the app, and so on. If you identify an uncommon issue, check if the services are up and running:
Online Deep Link Validators
Online deep link validators check if a given URL is properly set up for Universal Links (iOS) and App Links (Android). This allows you to check if the
assetlinks.json on a website is properly formatted for deep links as defined by Apple and Google, respectively.