Skip to content

The common failure

Why your link opens a web page inside Instagram.

Your association file is fine. Your entitlement is fine. The link never reached the operating system, so nothing you configured was ever consulted.

What is actually happening

A universal link works by the operating system intercepting a navigation and deciding an app should handle it. That decision happens in the OS, and it needs the navigation to reach the OS.

An in-app browser — the web view inside a social app, a messaging app, or a QR scanner with a browser built in — is a web view owned by that app. A tap inside it is often handled entirely within that process. The OS is never asked, so it never gets to say “actually, an app claims this domain”.

This is why the failure is so confusing: everything you would check is correct, and checking it again in a different way keeps confirming that it is correct.

How to tell it apart from a real misconfiguration

  • Paste the same URL into Safari or Chrome directly. If it opens the app there and not from the social app, your setup is right and this page is your problem.
  • Try the “open in browser” menu item inside the in-app browser. If that opens the app, same conclusion.
  • If it fails in a real browser too, it is configuration, and the two mechanisms compared will tell you which half to look at.

What can be done

Not “nothing”, and not “we solved it”. What is possible is a page that behaves correctly in the browser it is actually in.

When a link resolves in a context where an app switch may be refused, we serve an interstitial rather than assuming. It attempts the app, and it offers a button that does the same thing on demand — because a tap that silently goes nowhere leaves somebody stranded, while a button that they press themselves is a gesture the web view will usually honour. If the app does not come up, the page continues to the store rather than sitting there.

The button is deliberately a button and not a link: the script owns the navigation, so a browser that forbids the app switch still ends somewhere useful instead of nowhere.

What is still lost

Some web views will refuse every route to the app and there is no technique that changes that. In those cases the person reaches the store, installs, and deferred matching decides whether we can tie that install back to the link they tapped — to a measured degree, published on that page including where it does badly.

If somebody tells you they have eliminated this problem, ask which web views they tested and what happened in the ones that refuse.