URI redirect mode

Definition

URI redirect mode is a per-link setting on a deep link service that controls whether the link attempts to redirect the browser to a custom URI scheme before falling back, and what it does when that redirect fails.

This setting exists because of a problem the web cannot solve: a page has no reliable way to ask whether an app is installed. Every link service therefore has to guess, and the redirect mode is where you tell it how to guess. On a domain that is properly verified for Universal Links and App Links the guessing is no longer necessary, which makes the correct value for most modern setups the one that does the least.

The three modes

Vendors name the setting differently and number the modes differently — Branch exposes it as $uri_redirect_mode, others call it forced redirect or a strict flag — but the behavioural choice is always the same three. What matters is the middle column of the not-installed case, because that is where the setting either produces a clean fallback or an error the user sees.

Why detection does not work, and what "smart" is really doing

There is no web API that answers "is this app installed". The native check — canOpenURL on iOS, resolving an intent on Android — is only available to another installed app, and iOS additionally requires every scheme queried to be declared in LSApplicationQueriesSchemes. So a link service in smart mode is not detecting anything. It is applying heuristics: the user agent, whether the referrer suggests a surface that blocks scheme navigations, and in most implementations a timer.

// This is what a forced redirect looks like underneath. It is shown
// here to be recognised and removed, not copied.
const FALLBACK = "https://example.com/product/42";

let hidden = false;
document.addEventListener("visibilitychange", () => {
  // If the app opened, the page is backgrounded and we must not
  // navigate — otherwise the user returns to a store listing they
  // never asked for.
  if (document.hidden) hidden = true;
});

// Attempt the scheme.
window.location.href = "myapp://product/42";

setTimeout(() => {
  if (!hidden) window.location.href = FALLBACK;
}, 2000);

// Four ways this is wrong:
//  1. iOS may show a "Open in app?" confirmation. The timer keeps
//     running behind it, so the fallback fires mid-decision.
//  2. A backgrounded tab has its timers throttled, so the flag
//     is sometimes read before the event lands.
//  3. Chrome blocks scheme navigation without a user gesture, so
//     on a redirect page the first line silently does nothing.
//  4. The 2000 ms is a guess. Slow devices exceed it; fast ones
//     make the error visible before it elapses.

The third point is the one that quietly invalidates the whole approach on Android. Chrome requires a user gesture for a scheme or intent:// navigation, and an interstitial redirect page has no gesture — the click happened on the previous page. So a forced redirect on Android frequently does nothing at all rather than failing loudly, and the fallback timer becomes the only path that ever runs.

The setting you want, and the one thing that actually breaks

With a verified domain, none of this applies. The operating system intercepts the https:// URL before a browser is involved, so the app opens with no redirect, no scheme, no timer and no error — and when the app is absent, the same URL simply loads as a web page. That is the behaviour smart mode is trying to approximate, achieved properly.

# FORCED. The 302 to a custom scheme is what the browser errors on.
GET /l/abc123 HTTP/1.1
Host: links.example.com

HTTP/1.1 302 Found
Location: myapp://product/42
# → app opens, or "the address is invalid"


# VERIFIED. No scheme anywhere. The OS claims the URL before the
# request is made; if it does not, this is just a web page.
GET /product/42 HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: text/html
Link: <https://example.com/.well-known/apple-app-site-association>; rel="alternate"

If you inherited forced mode and cannot yet verify the domain, the pragmatic order is: fix assetlinks.json and the AASA file first, confirm verification on a real device, then switch to smart and delete the interstitial. Changing the mode before the verification lands just moves the failure from an error page to a silent no-op — which is harder to notice and identical from the user's side to a deep link opening the browser instead of the app.