Deep links and routing
Valence maps a link opened by the OS to a path inside your signed web UI. The
WebView stays on its loopback origin. Schema 9 adds link.initial, link.opened
and the web helper onLink. This implements contracts §6.3. Android is the tested
platform; iOS is experimental and untested.
Choose which links this store build accepts
Section titled “Choose which links this store build accepts”Migrating an older app? A custom link.initial declared below since: 9 stays
app-owned, including a shipped string? return. Keep its native handler, custom
link.opened emitter and routing adapter; onLink expects the modern {url, path}
shape. Leave links.origins empty when retaining your own native listeners.
Do not change shipped signatures, payloads or since values, and do not rebaseline.
The template’s schema-9 method delegates to the package and retains strict shape
checks. An unshipped copy of that modern shape below 9 is refused with the correct
reserved number. See migration.
Add to valence/valence.config.json, run codegen and ship a store build:
{ "links": { "origins": ["https://links.example.com", "myapp://app"] } }Use exact lowercase origins, without a trailing slash, wildcard, credentials or
path. HTTPS permits a non-default port; custom schemes require a host and no port.
HTTP and executable/file schemes are rejected. An empty list disables links. This
list is independent of http.origins and web.connect; an OTA cannot enlarge it.
Native manifest registrations must match it too.
Both halves are mandatory, and they live in different files: this list is compiled
into the store build, while the intent filter below is hand-edited into the Android
manifest that codegen never reads. Each half failing alone is silent in its own
direction. With the origin set and no filter, every check passes and the OS simply
never routes the link (adb shell am start answers unable to resolve Intent). With
the filter present and no origin, the app launches — which looks like success — and
the host then rejects the URL as untrusted, so your page gets nothing.
npx create-valence doctor pairs them in its deep links row: it fails for a declared
origin no VIEW filter serves, and warns for a filter this list does not declare. It
reads android/app/src/main/AndroidManifest.xml and compares scheme and host, so add
both halves in the same commit, and prove it on a real build — no unit test and no
browser shim can exercise the manifest half:
adb shell am start -a android.intent.action.VIEW -d 'myapp://app/shelf'myapp://app/shelf?sort=new#note becomes /shelf?sort=new#note. The authority
app is an allowlisted host, not a path segment. The runtime rejects malformed
URLs, control characters, dot segments, encoded path separators, backslashes,
network paths and /_host destinations, and caps URLs at 8 KiB UTF-8.
Links are input, not authorization. Custom schemes can be claimed by other apps. Use verified HTTPS links for sensitive flows; authenticate actions separately and validate any login callback against your own state/PKCE flow. Valence does not extract tokens or call native methods from a link.
Connect your web router
Section titled “Connect your web router”import { connect, onLink, ready } from './valence/bridge.g';
await connect();const stopLinks = onLink();// Render your router; call ready() on every path that paints.await ready();// On root unmount: stopLinks();With no handler, onLink() pushes the validated local path with history.pushState
and dispatches popstate. It does not reload the page or visit the external URL.
Your router must listen to History API navigation. For routers with their own API:
const stopLinks = onLink(({ path }) => router.navigate(path), reportError);The handler also receives initial, which says which arrival this was: true for the
link that was waiting when the page started, false for one opened while the app was
already running. The helper has always known the difference — it is what makes a live
event supersede a pending launch reply — and this is how it tells you, so you can write
the cross-source rule below without hand-rolling the subscription.
const stopLinks = onLink(({ path, initial }) => { if (!initial) return arbiter.apply(path); // a live tap always wins arbiter.applyLaunch(path); // the first launch reply; later ones are dropped});initial is added by the client, not sent by the host, so there is no schema to check and
no has() gate. Handlers that ignore it keep working unchanged. If you want to name the
parameter type for a router function declared elsewhere, your generated bridge.g.ts
re-exports ReceivedLink (and AppLink), so you never need to import from
@getvalence/bridge yourself. If your own schema happens to declare a type with one of those
names, your type wins and only that one re-export is dropped — regenerating never renames a
type you have shipped, and never emits the same name twice.
Install one subscription at the app root after connect(). Unsupported schemas,
older hosts and browsers without a link.initial shim are a no-op. The helper
subscribes before requesting the initial link, drops a delayed initial reply if a
live event arrived, and stops pending navigation after cleanup. A browser shim may
return {url,path} or null from link.initial.
A cold start can carry more than one destination, and the last event wins — not the last await.
link.initial and notify.initial are separate mailboxes, each answering “did the OS start me with
one of these?”, and a boot that asks both gets two answers in whatever order the two awaits happen to
resolve. Code that applies them in a fixed order — read the link, then read the reminder, then route to
the reminder — routes to the older one whenever the user’s actual tap was the link. onLink() already
does the right thing within its own source: it subscribes before it asks, and drops a late initial reply
if a live event has arrived. Across sources it is yours to do, and it is one line of discipline: record
which destination arrived most recently, apply that, and have each handler clear the other’s pending
target. Pass over a pending initial reply once a live event has superseded it, rather than letting the
await order decide. App-c reproduced the failure in an isolated scheduler before it ever saw it on a
device, which is the cheap way to find it.
With initial on the link side and the two names notify.initial / notify.tapped on the
notification side, both sources now label themselves, so one shared arbiter can hold the rule: a live
event always applies, the first launch reply applies, every later launch reply is dropped.
One part of this is not solvable, and it is worth knowing where the floor is. Neither launch mailbox carries an arrival time, so “most recently” can only ever mean the order your page observed, never the order the user tapped. On a cold start holding both a tapped reminder and a deep link, whichever mailbox resolves first wins, and it may be the older tap. Closing that needs a timestamp on both initial replies, which is a schema change and is not in 0.4. The rule above is the limit of what a page can do today, and it is worth doing: it fixes every case where the two arrive at different times.
There used to be a third destination your page could not see, and that one is fixed in the host. If
Android had reclaimed the task, a cold start also restored the route the user was last on — and the
host loaded it before your page existed, so an arbiter doing the above perfectly could still be looking
at a screen neither mailbox chose. A launch destination in any mailbox now pre-empts that route: the
host opens / and leaves the choice to you, keeping the saved draft. See
state restoration.
For manual integration, subscribe to link.opened before calling
call('link.initial'). The call consumes the latest pending accepted link once;
it returns null on later calls unless a new page has started. Each WebView page start re-arms the mailbox, retaining pending links without replaying consumed ones. Until that call,
links replace the pending mailbox (latest wins). Afterwards they are live events,
including repeated taps on the same URL. The helper reports errors through its
second callback; the default logs a fixed message without URL contents.
Android native setup
Section titled “Android native setup”Inside the existing singleTop, exported main activity, disable Flutter’s default
deep-link routing and add separate filters:
<meta-data android:name="flutter_deeplinking_enabled" android:value="false" /><intent-filter> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="myapp" android:host="app" /></intent-filter><intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" android:host="links.example.com" /></intent-filter>Generate the website association document, using colon-separated SHA-256 bytes:
npx create-valence assetlinks --package com.example.app --fingerprints AA:BB:... --out website/publicReplace AA:BB:... with the full 32-byte signing certificate fingerprint (not a
Valence Ed25519 key). For Play App Signing, use the app-signing certificate from
Play Console, not the upload certificate. Multiple certificates are comma-separated.
The command writes website/public/.well-known/assetlinks.json, refuses invalid
input, and works without a Valence project. It never overwrites an existing
document — that file grants an app every URL path on the domain and is reviewed
before upload, so a silent rewrite is how a stale fingerprint survives a key
rotation. The refusal says so; read the existing file, then delete it to regenerate.
Review it before
uploading; it grants the specified app all URL paths on that host.
Serve it at https://links.example.com/.well-known/assetlinks.json with JSON
content type, no redirects and no authentication. This command does not deploy,
edit the native manifest or verify ownership of a domain.
adb shell pm verify-app-links --re-verify com.example.appadb shell pm get-app-links com.example.appadb shell am start -W -a android.intent.action.VIEW -d 'myapp://app/shelf?sort=new#note' com.example.appadb shell am start -W -a android.intent.action.VIEW -d 'https://links.example.com/shelf' com.example.appTest a cold start, a warm app and repeated taps. For local tests without a hosted
association document, adb shell pm set-app-links --package com.example.app 2 links.example.com forces OS approval. This tests intent delivery, not real domain
verification. Reset with state 0 afterwards. Inspect pm get-app-links separately
to distinguish a fetched verification result from a forced one.
iOS setup (experimental, untested)
Section titled “iOS setup (experimental, untested)”Set FlutterDeepLinkingEnabled to false in Info.plist. Add custom schemes to
CFBundleURLTypes. For Universal Links, enable Associated Domains with
applinks:links.example.com in the signed app’s entitlements and configure the
Apple app identifier and provisioning profile accordingly.
npx create-valence aasa --app-id ABCDE12345.com.example.app --out website/publicThis writes .well-known/apple-app-site-association with applinks and paths: ["*"]. The 10-character prefix is your Apple Team ID. Serve it over HTTPS with
JSON content type and no redirect. The example includes native setup for the
placeholder domain links.example.invalid; it cannot verify against that domain.
No Apple hardware has tested either custom schemes or Universal Links here.
Primary setup references, checked 2026-10-22: app_links, Android association files, Android verification, Apple associated domains.
Unreleased integration branch
Section titled “Unreleased integration branch”The reserved R6 methods and event have since: 9. This intermediate branch also
contains upstream account security at schema 13, so its template and example report
13. Integrate the remaining reserved surfaces before publishing this host; the
number alone cannot describe a partial feature set. Apps number their own schemas,
so use the generated onLink() helper or has('link.initial') for support.