🔗 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).

• Branch - Apple Universal Links

  • 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.

• Branch - Deep links do not open the app

  • Explains great examples of why your deep links might not be opening the app. Definitely a must-read.

• Branch - Viewing deep link data

  • Example specific to Branch on how to view deep link data: simply add ?debug=1 to the end of your deep link. (Works for Branch’s deep links only)

• Branch - 3 Steps to Troubleshoot iOS 9 and iOS 10 Universal Links

• AppsFlyer - OneLink troubleshooting and FAQ: This is a great resource for troubleshooting OneLink issues, including (but not limited) to answering these questions:

  • Which method should I use for opening apps — Universal Links, App Links, or URI schemes?

  • Which operating systems allow URI schemes to open the app?

  • Do I need to update the app after iOS Universal Links and Android App Links setup?

  • Can I redirect existing users to a web page instead of the app?

  • Can I redirect tablet users to a different app or URL then mobile app users?

  • Can I assign an app to multiple OneLink templates?

  • Can I delete a OneLink template?

  • Can I change the subdomain in a OneLink template?

  • Can the domain/subdomain of a OneLink template be applied to the template ID of another template?

  • Can I use the same subdomain for more than one template?

  • How can I redirect desktop users?

  • How can I redirect Chrome OS users?

  • Does OneLink work without the AppsFlyer SDK?

  • What methods are available for creating OneLink custom links?

  • Can OneLink custom links open the app from a browser?

  • Why doesn't the OneLink URL open the app or deep link existing users?

  • Why does my OneLink URL open a blank page in Chrome?

  • Can I use OneLink for redirection on Brave?

  • Do OneLink custom links take longer to load than other links?

  • How can I record the cost per install when using OneLink?

  • How can I prevent parameter forwarding on redirections?

  • Are single-platform custom links still available?

  • Can I change the short URL ID after saving a link?

  • Can I wrap and shorten OneLink (or deep links)?

  • Can I use OneLink (or deep links) in emails?

  • How do users get redirected to their regional app store?

  • Why isn't my OneLink URL redirecting users to the specified domain?

  • What parameters are mandatory for OneLink custom links?

  • Can parameters be appended to the short URL?

  • What custom media source names can I use?

  • What attribution parameters can be added to a OneLink?

  • Are custom parameters added to OneLink custom links available in raw data?

  • Are parameter names case sensitive?

  • Can I use deep links in social apps (unpaid)?

  • Can I use deep links with ad networks (paid)?

  • How can I solve the iOS app-launching issue from social media apps?

  • Can I use deep links on Instagram?

  • Can I use deep links for redirection on WeChat?

  • Why are Android users with the app installed being redirected to a web URL and not into the app when they click a link on Facebook webview?

  • How can I A/B test the Social app landing page?

  • How can I bypass the app selection dialog?

  • What deep linking methods should be implemented?

  • Can a URI scheme (af_dp parameter) be used for deep linking?

  • Does OneLink deep linking work for iOS 14?

  • Does OneLink deferred deep linking work for iOS 14?

Deep Link Developer Documentation

• AppsFlyer - iOS Unified Deep Linking

  • Has a super helpful visual diagram of how deep linking works on iOS, and explains some implementation details.

• Branch - Create Ad Links

  • Explains how Ad Links should be created.

• Branch - Universal Email Integration Guide

  • 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

• Branch - Deterministic Matching

• Branch - Predictive Modeling

• Branch - Probabilistic Modeling

• Branch - SKAdNetwork

  • Explains how SKAdNetwork works, in particular with Branch.

  • Contains lots of helpful tables and a visual diagram of how SKAdNetwork works.

• AppsFlyer - Making sense of Universal Links and App Links

• Branch - Best Practices to Secure User Opt-In on iOS 14

• Branch - A Marketer-Friendly Guide to SKAdNetwork Conversion Values

• Branch - NativeLink and App Clips: Solving the Deferred Deep Linking Challenges of Private Relay

• Branch - Glossary

  • An extensive glossary on common terms used around the industry, engineers, and marketers.

• AppsFlyer - Glossary

  • 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:

A gallery of App Tracking Transparency (ATT) prompts — A collaborative effort to gather as many live App Tracking Transparency (ATT) prompt examples as possible.

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:

• https://status.appsflyer.com

• https://status.branch.io

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 apple-app-site-association and assetlinks.json on a website is properly formatted for deep links as defined by Apple and Google, respectively.

• https://branch.io/resources/aasa-validator - iOS only.

• https://www.appsflyer.com/tools/link-validator - Android and iOS.

• https://yurl.chayev.com - Android and iOS.