Universal Links first appeared in iOS 9. According to Apple’s Supporting Universal Links document:

When you support universal links, iOS 9 users can tap a link to your website and get seamlessly redirected to your installed app without going through Safari. If your app isn’t installed, tapping a link to your website opens your website in Safari.

This is a great idea in principle, since one URL can serve two purposes without needing to use custom URL schemes, but Universal links were not working as advertised for me and I figured out why. If you are having problems getting Universal links to behave as expected, I hope this article can help.

The Problem

“Open In App” Opens an app’s App Store page instead of the app

I use imgur and have its associated app installed on my phone, but I noticed that the “Open In App” buttons that appear on its mobile site (highlighted below) all loaded the App Store page for the imgur app instead of loading the content inside the imgur app as the buttons claimed they would.

I figured there was some glitch with the buttons that was mistakenly redirecting me to the App Store. Imgur’s App Store page showed the “Open” button that normally appears when you look at an App Store page for an installed app, so for a while it never occurred to me to press the button since I figured it would just open the app to its default state, just like it does when manually viewing its App Store page by searching for it in the App Store.

I was wrong.

It turns out that tapping the Open button on an app’s App Store page after being redirected to it by tapping a Universal Link will open the linked content in-app, rather than the default/front page of the app.

There is no visual indication that App Store page “Open” buttons have different behaviors when being redirected from a Universal Link versus browsing the App Store manually, even though this is clearly the case.

Regardless, I expected “Open In App” to actually load the linked content in-app and not to add an extra step of loading an app’s App Store page.

The Realization

After doing some Internet digging, bullet point 4 of this StackOverflow answer shed some light on the situation.

First, some terminology: I will refer to a Universal Link as enabled if tapping it causes content to load in-app, and disabled if tapping it causes content to load in a web page or causes an App Store page to open.

It turns out that different URL paths under a single domain name can be independently set to have their corresponding Universal Link behavior be enabled/disabled depending on how the developer configured them (see the “Creating and Uploading the Association File” section of Apple’s Supporting Universal Links document), and that the per-Universal Link setting stays in effect until it is changed again.

This means that the instructions below may need to be repeated multiple times for a single site.

Another factor that adds to the confusion is that there is no way to tell whether a given Universal Link is enabled/disabled other than tapping it to see what its behavior currently is.

The Solution

Enabling a Universal Link

If tapping a Universal Link currently opens a web or App Store page as described above but you want the link to cause content to load in-app, that means the Universal Link is currently disabled. Here’s how to enable it:

1. Try pulling down/scrolling up on the web site when the page view is already scrolled all the way to the top to reveal an Open in the [App Name] App banner as pictured below:

   

   Tapping the banner will enable the Universal Link and cause the content to load in-app.

2. If no banner appears as shown above, tap and hold on the Universal Link until a dialog with buttons appears. If you scroll through the buttons, one should say Open in "[App Name]" as pictured below:

   

   Tapping the Open in "[App Name]" button will enable the Universal Link and cause the content to load in-app.

Once the Universal Link is enabled (content loads in-app), it will always load in-app in the future unless you [re]disable the Universal Link as described below.

Note that when tapping a disabled Universal Link causes a redirection to an app’s App Store page, tapping the “Open” button on that page will cause content to load in-app that one time, and will not enable that Universal Link for future use as described above.

Disabling a Universal Link

If tapping a Universal Link currently causes content content to load in-app but you want the link to open a web (or App Store) page, that means the Universal Link is currently enabled. Here’s how to disable it:

When content has loaded in-app after tapping a Universal Link, you should see some text at the very top-right of the screen in the iOS status bar with the domain name of the page whose Universal Link redirected you to that app, as pictured below:

Tapping that text will cause the content to open in a web (or App Store) page and will disable the Universal Link that opened the app.

Once the Universal Link is disabled (content doesn’t load in-app), content will never load in-app in the future unless you [re]enable the Universal Link as described above.

If you want to view content from an enabled Universal Link on the web after its content loads in-app just one time/without disabling the Universal Link entirely, don’t tap the Status Bar text; instead, just switch back to your web browser.

A Note on App Store Page Redirection

The behavior of disabled Universal Links causing redirections to an App Store page instead of loading content in a web page appears to be web site-specific.

In the case of my imgur example, the App Store redirection seems to be functionality that imgur explicitly implemented to try to steer users towards using their app instead of their web site, since tapping a disabled Universal Link on imgur’s web site does appear to load another page on the web site for a split second before redirecting to imgur’s App Store page. In other words, the Universal Link correctly opens imgur’s web site as expected, which itself then redirects to imgur’s App Store page (where the “Open” button would cause the content to load in-app one time as described above.) It’s possible that other sites would load web content in a web page as expected when tapping a disabled Universal Link, rather than redirecting users to an App Store page as is the case for imgur.

Conclusion

The mechanisms built in to iOS for enabling and disabling Universal Links are difficult to understand, and the fact that settings are sticky/permanent and can independently vary across given Universal Links under a single domain is not made apparent whatsoever by the UIs iOS provides around this feature.

This confusion is compounded when developers implement behavior that causes web sites to open App Store pages when tapping disabled Universal Links (as imgur seems to have done), causing content not to open in a web view as expected, despite the fact that the Universal Link is disabled.

“Open in App” links behaving differently than I expected was a large source of frustration for me when browsing the web on iOS. Given how confusing this issue was to understand, solve, and then write about, I hope this article was helpful.