ZipQuantum Engineering ·
Tauri Deep Links: A Tested iOS, Android and Desktop Reference
Build Tauri 2 deep links with Universal Links, Android App Links, deferred delivery and desktop single-instance handling using a tested reference.
A Tauri application can receive the same ZipQuantum Smart Link before install, after install and while an existing desktop process is already running. The difficult part is not registering a URL scheme. It is preserving one clear trust boundary across a Rust shell, a webview, Android and iOS without turning tokens or route receipts into application state.
This is why the ZipQuantum mobile examples repository now includes a tested Tauri 2 reference implementation. The work began as a community proposal, was reviewed in public, and was merged only after its platform and CI boundaries were explicit.
1. What the reference covers
The merged example uses the existing ZipQuantum mobile-v1 contract on mobile and deliberately keeps desktop narrower. It handles direct delivery, deterministic post-install recovery, cold and warm launches, application-route allowlisting and one-shot mobile acknowledgement.
| Runtime | Direct delivery | Deferred delivery | Route acknowledgement |
|---|---|---|---|
| iOS | Universal Link | Visible, user-initiated UIPasteControl; one read |
Once, after route render |
| Android | Verified App Link | Google Play Install Referrer; one read | Once, after route render |
| macOS, Windows, Linux | Custom scheme plus single-instance handling | Out of scope | Out of scope; never sent |
Those differences are intentional. Mobile has an installed-app identity that the server can bind to a recovery operation and receipt. The desktop example currently has no equivalent trust contract, so it parses a configured custom scheme locally and never sends a mobile acknowledgement.
2. How one delivery model spans four runtimes
Cold-start and warm-start events enter the same allowlisted route parser. This avoids a common failure mode where the first launch validates an incoming URL correctly but a second-instance event takes a less restrictive path.
The receipt lives only inside the pending in-memory navigation closure. The reference does not manufacture, decode, sign, persist, print or replay it. Error messages also avoid full URLs, handoff tokens and receipt values.
One parser
Direct and deferred events share the same host and destination-route allowlist.
One-shot state
A pending recovered route can be consumed only once per process.
Render first
Mobile acknowledgement happens only after the destination screen is visible.
3. Where Android, iOS and desktop differ
Android: Install Referrer as a deterministic handoff
Android extracts zq_token and zq_host from Google Play Install Referrer. The adapter reads the referrer once per process and hands only the parsed values to the shared flow. There is no advertising identifier, device fingerprint or probabilistic matching.
iOS: a visible paste action
iOS presents a native modal whose recovery action is implemented by UIPasteControl. The app does not read the clipboard at launch and does not use a generic clipboard API. The user can see and initiate the recovery action, which keeps consent and platform behavior explicit.
Desktop: single instance before deep-link registration
The Rust shell registers the single-instance plugin before the deep-link plugin. Initial launch and subsequent zq-example:// launches both feed the same handler in the webview. Deferred delivery and route_ack are not implemented for desktop.
4. How to run the reference
Clone the public examples repository, install the locked dependencies and run the focused checks:
git clone https://github.com/ZipQuantum/zipquantum-mobile-examples.git
cd zipquantum-mobile-examples/tauri
npm ci
npm test
npm run typecheck
npm run build
npm run tauri devThen replace the placeholders only with values verified in your ZipQuantum dashboard:
links.example.cominsrc/config.tsandsrc-tauri/tauri.conf.json;app.example.comand the permitted application routes insrc/routing.ts;com.example.zipquantum.tauriin the configuration and Tauri bundle identifier.
The iOS and Android identifiers must match the bundle identifier because mobile-v1 binds recovery and acknowledgement to the installed application. Do not commit a live token, certificate, provisioning profile, handoff URL, receipt or user data. Before device testing, validate the host’s AASA and assetlinks.json files with Deep Link Doctor.
5. What the validation proves
Pull request 13 merged at commit 86a88514f06aec43db0f505af5c3716af42acbc9 after all 12 GitHub checks completed successfully. The workflow ran the repository static checks and platform jobs for Android, iOS, Flutter, React Native and Tauri.
The focused Tauri tests cover cold and warm direct delivery, serialized warm URLs, deferred delivery, rejected routes, one-shot acknowledgement and the desktop no-ack boundary. The repository validators also use stable ZQ_OK, ZQ_WARN and ZQ_ERROR prefixes so CI output stays deterministic.
This evidence validates the reference at the merged commit. It does not certify an application after its domains, identifiers, routes or native platform configuration have changed. Re-run the validators and a real-device matrix for every downstream implementation.
6. What to verify before production
- Verify the link host in your ZipQuantum workspace and configure its Universal Link and Android App Link associations.
- Keep the bundle/application identifier identical across Tauri configuration and
mobile-v1calls. - Reduce every destination to a known application route; reject arbitrary web destinations.
- Test direct links on cold start and while the app is already running.
- Test Android Install Referrer after a clean Play installation.
- Test the visible iOS handoff and confirm there is no silent clipboard read.
- Confirm mobile acknowledgement occurs only after the intended screen renders and only once.
- Confirm desktop never calls the mobile acknowledgement endpoint.
- Inspect logs and crash reports for tokens, receipts, full handoff URLs and user data.
Start from the reviewed reference, then prove your own app boundary.
Read the implementation, replace the documented placeholders and run the same deterministic validation before shipping.
Frequently asked questions
Is this an official Tauri integration?
No. It is a reference/community implementation maintained by ZipQuantum. It is not produced or endorsed by the Tauri project, and it is not a published app-store application.
Does the example add a proprietary ZipQuantum SDK?
No. It uses the documented ZipQuantum mobile-v1 HTTP contract, standard Tauri plugins and small native Android and iOS adapters. Your app still needs one-time native platform setup and its own route handling.
Why does desktop not send route acknowledgements?
The current mobile acknowledgement is bound to an installed mobile app identity. A separate desktop identity and trust contract has not been defined, so desktop acknowledgement and deferred delivery remain out of scope.
Can iOS recover a route without a visible user action?
No. The reference uses a visible native UIPasteControl. It does not read the clipboard silently at launch or use a generic clipboard API.