Desktop → Mobile Handoff
How the widget moves a verification from a desktop to the user's phone when a step needs hardware the desktop doesn't have — automatically.
Some verification steps need capabilities a laptop doesn't have — most commonly a phone camera for document capture or a wallet app for a mobile driver's license. When that happens, the widget offers a desktop → mobile handoff: it shows a QR code, the user continues on their phone, and the desktop picks the result back up. This is built into the widget — you don't implement it — but it surfaces on the session object, so this page explains what's happening and how to observe it.
Handoff does not add browser NFC support
nfc_passport requires Stile's supported native NFC bridge. Standard Web NFC cannot read an ICAO
passport chip, so handing a browser session from desktop to an ordinary mobile browser is not
enough. Include document_capture as a fallback for web integrations, or use a supported native
embed for passport-chip reads.
How it works
It's automatic
The widget decides when a handoff is needed based on the workflow's methods and the current device. You don't trigger it; you just see the session move between devices.
- The user starts verification on their desktop.
- A step requires a supported phone capability (such as a camera or wallet). The widget renders a QR code and a countdown.
- The user scans it and continues on their phone — the hosted verification page takes over there.
- While the phone holds the flow, the session is locked to that device.
- On completion, the lock releases and the desktop's poll sees the terminal result.
Observing it on the session
The session object reflects the handoff state, so a desktop client (or your backend) can render a "continue on your phone" state while the phone is active:
| Field | Meaning |
|---|---|
active_device | "mobile" while the phone holds the lock; null otherwise. |
device_locked_at | Unix timestamp (seconds) when the current device took the lock. |
The lock clears automatically after a terminal status, an explicit release, or a short idle timeout — so a desktop poll never gets stuck waiting on an abandoned phone session.
Lightweight status polling
The widget polls a lightweight session-status endpoint (authenticated with the session's
client_secret) to track the handoff without exposing full session data to the page. If you build
a custom desktop UI, retrieve the session from your backend and read active_device the same way.
Customizing the hosted page
The QR code points at Stile's hosted verification page. If you run the widget through the Widget SDK, the verify-url attribute (or verifyUrl option) sets which hosted page the QR targets — useful for local development against a non-production verify URL.
The phone-side widget never offers a second handoff (there's nothing to hand off to), so the experience is a single hop: desktop → phone → done.