Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

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.

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:

Terminal window
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.

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.

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:

Terminal window
npx create-valence assetlinks --package com.example.app --fingerprints AA:BB:... --out website/public

Replace 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.

Terminal window
adb shell pm verify-app-links --re-verify com.example.app
adb shell pm get-app-links com.example.app
adb shell am start -W -a android.intent.action.VIEW -d 'myapp://app/shelf?sort=new#note' com.example.app
adb shell am start -W -a android.intent.action.VIEW -d 'https://links.example.com/shelf' com.example.app

Test 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.

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.

Terminal window
npx create-valence aasa --app-id ABCDE12345.com.example.app --out website/public

This 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.

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.