Universal & Deep Links: 2026 Complete Guide

Source: Dev.to

Plan

Universal Links and App Links only work when four layers line up correctly. In this guide, we’ll walk through each one:

Your domain

How to set up AASA and assetlinks.json so iOS and Android trust your URLs.

Your mobile apps

What needs to be in your iOS entitlements, Android manifest, and native URL handlers.

Your hosting or framework

How platforms like Next.js, Firebase, or Vercel can break Universal Links if they rewrite or redirect files.

Your client‑side logic

How to map URL paths and query params inside React Native so the right screens open.

By the end, you’ll understand how these pieces fit together, why Universal Links often fail silently, and how to debug them quickly when they do.

Deep linking basics

Before we get into implementation, it’s important to understand the two types of deep links you’ll deal with: custom URL schemes and Universal/App Links. Both open specific screens inside your app, but they behave very differently and serve different purposes.

Custom URL schemes

Custom schemes look like:

myapp://reset-password?token=123

They’re simple and useful for internal navigation, but they come with serious limitations:

• They only work if the app is installed.
• There’s no fallback (the link does nothing otherwise).
• Any other app can register the same scheme.
• Some apps and email clients block them completely.

Custom schemes are still good for certain in‑app flows, but they’re not reliable for anything being sent from outside the app.

Universal Links (iOS) and App Links (Android)

This is the modern approach. Both platforms moved to secure deep links based on HTTPS + domain verification.

A Universal/App Link looks like a regular link:

https://example.com/reset-password?token=123

• If the app is installed, it opens the correct screen.
• If it’s not installed, the link falls back to the website.

Because the system verifies that your app “owns” this domain, these links are:

• More secure
• More predictable
• Supported across email, SMS, browsers, and most apps
• Designed to avoid hijacking or the wrong app opening your link

When to use what

• Use Universal/App Links for anything coming from outside your app (email verification, invitations, password reset, shared links, notifications).
• Use custom URL schemes for deep navigation within your app (especially when moving between webviews or hybrid screens).

How universal & app links work

To make Universal Links (iOS) and App Links (Android) behave reliably, it helps to understand what actually happens when a user taps one. The OS doesn’t simply “open your app.” It runs a sequence of checks before deciding whether your link is trustworthy. This is the part most developers never see, and the reason Universal Links often fail without explanation.

The OS decision flow

Domain verification

Universal/App Links rely entirely on domain verification. If the OS can’t fetch your verification files, or if they’re served incorrectly, Universal Links will never open your app, no matter how perfect your mobile code is.

Common reasons verification fails:

• Verification files behind redirects
• Wrong Content‑Type header (e.g., text/html instead of application/json)
• Hosting platform rewriting routes to index.html
• Wrong domain (e.g., www.example.com instead of example.com)

Once the OS fails verification, it often caches that failure, which is why uninstalling the app is sometimes required during testing.

App installed vs. not installed

After verification, the OS chooses between two outcomes:

If the app is present, the link opens the app; otherwise, the link opens the website. This is a major advantage over custom URL schemes: the user always lands somewhere meaningful.

Real‑world scenarios

Universal/App Links are most commonly used for:

• Email verification
• Password reset
• Invite flows
• Shared content
• Notifications that deep link into the app
• Webview → app handoff

All these flows rely on the same OS decision logic, so a single misconfigured domain can break them all at once.

Web setup

Universal Links and App Links only work if your domain is configured correctly. This is the most sensitive part of the entire setup and the part that breaks most often. If iOS or Android can’t read your verification files with the exact format and headers they expect, the app will never open, even if everything else is perfect.

Verification files

Both platforms expect a file at a very specific path.

iOS – apple-app-site-association

/.well-known/apple-app-site-association

• Must be raw JSON (no .json extension)
• Must be served with Content-Type: application/json
• Must return HTTP 200

Android – assetlinks.json

/.well-known/assetlinks.json

• Must be a valid JSON array
• Must contain the package name and the SHA‑256 certificate fingerprint
• Must be served with Content-Type: application/json and HTTP 200

These files tell the OS: “This domain belongs to this app. It’s safe to open links directly.” If the OS can’t load or parse them, Universal/App Links will silently fail.

File hosting requirements

The OS expects all of the following to be true:

• HTTPS only (no HTTP)
• No redirects (even a single 301 or 302 breaks verification)
• No authentication or cookies required to fetch the file
• Exact path: /.well-known/ must be literal
• Correct Content‑Type header (application/json)
• Status 200 response
• No index.html fallback (common issue with frameworks like Next.js)

If your hosting platform rewrites URLs or forces HTML responses, the OS won’t accept your domain.

Server constraints & checklist

Quick checklist to confirm your domain setup is correct:

• Both files live in /.well-known/
• Files are served over HTTPS with a valid TLS certificate
• No redirects (direct 200 response)
• Correct Content-Type: application/json header
• Files contain valid JSON (raw for iOS, array for Android)
• Android file includes correct package name and SHA‑256 fingerprint
• No authentication, cookies, or other request modifiers required
• No fallback to index.html or other rewrite rules

Once this checklist is satisfied, the OS should be able to verify your domain, and Universal/App Links will work reliably across platforms.