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 hardware a laptop doesn't have — a camera for document capture, NFC for an ePassport, 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.
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 mobile hardware (camera, NFC, or a 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.
Next steps
Returning User Verification
Verify once, reuse many times — VP tokens, credential lookup with OTP, and the strength, age-tier, and expiry rules that decide when a user must re-verify.
Trust Reuse
Accept verifications a user already completed at other Stile operators — verify once, recognized everywhere.