How to Build a Deep Link That Falls Back

You send a link to a product in your app. Users who have it installed open the app on that product — perfect. Users who don’t get a browser error page saying the address is invalid, because myapp://product/12345 means nothing to a device without the app.

That’s the difference between a custom scheme and a universal link, and it’s the whole reason universal links exist.

Two mechanisms, one obvious winner

Custom schemes (myapp://) were the original approach. The operating system maps the scheme to an app. If no app claims it, the link fails — usually with a browser error, sometimes with nothing at all. There’s no graceful path for someone who hasn’t installed your app, which is most people receiving a link.

Universal Links on iOS and App Links on Android use a normal https:// URL. If the app is installed and verified as the owner of that domain, the system opens the app. If not, the browser loads the page.

Same link, two behaviours, and the fallback is the website that was already there. This is the correct default for nearly every case.

The association file

The verification is what people get wrong. The system checks that the app is genuinely allowed to handle links for that domain by fetching a file from it:

• iOS: /.well-known/apple-app-site-association
• Android: /.well-known/assetlinks.json

Both must be served over HTTPS, with the correct content type, no redirects, and reachable without authentication. iOS additionally caches the result, sometimes for a long time, which makes debugging slow — a fix can take a reinstall to take effect.

When a deep link silently opens the website instead of the app, the association file is almost always the reason.

Deferred deep linking is a different problem

Sending a user who doesn’t have the app to the store, then opening the right screen after installation, isn’t something a link can do on its own. The link is gone by the time the app first launches.

Solving it requires a service that records the intent — usually by fingerprint or by a clipboard token — and hands it to the app on first run. That’s a third-party product, not a URL format, and it’s worth knowing before you promise the behaviour.

Common mistakes to avoid

• Using a custom scheme for links you send to people who may not have the app.
• Serving the association file with the wrong content type, or behind a redirect.
• Testing only on a device with the app installed, which never exercises the fallback.
• Forgetting that the fallback web page should show the same content as the app screen, not a generic landing page.
• Assuming iOS will pick up an association file change immediately — it caches.

How to do it with Deep Link Builder

The Deep Link Builder constructs the link and the fallback together.

1. Choose universal links unless you have a specific reason not to.
2. Set the in-app path and the equivalent web URL, which should show the same content.
3. Copy the link and test on two devices — one with the app, one without.
4. Verify the association file is reachable over HTTPS with the right content type.

Apple’s Universal Links documentation and Android’s App Links guide cover the platform specifics. Other developer tools are in the tools directory.

Frequently asked questions

Universal link or custom scheme?

Universal links, wherever possible. A custom scheme fails with an error page when the app isn’t installed, while a universal link simply opens the website.

Why does my deep link not open the app?

Usually the association file — missing, unreachable, or served with the wrong content type. Both platforms fetch it over HTTPS and cache the result.

What is deferred deep linking?

Sending a user without the app to the store, then routing them to the right screen after install. It needs a service to carry that state across the installation; a plain link can’t.

Final thought

Test on a device that doesn’t have your app. That’s the case the link exists for, and it’s the one nobody checks.

Try the free Deep Link Builder