Venues

The SDK opens a session in one of three venues, chosen automatically for the customer’s context: an embedded iframe for the phone-verification rail, a popup window for wallet-based sign-in (so a browser extension like MetaMask can prompt normally), and a full-page redirect as the fallback when neither embedding nor a popup is viable.

Your integration doesn’t need to pick a venue itself — you configure callbacks once, and they fire the same way regardless of which venue the SDK ends up using.

Choosing a venue

The flow option decides which venue opens:

flow	Venue	Rail
'phone'	iframe	Phone / SMS
'wallet'	popup	Wallet sign-in
'auto' (default)	chooser	The customer picks phone or wallet from a small built-in overlay

The SDK has no reliable client-side signal to guess the rail for you — no wallet-provider probe, no user-agent sniffing — so 'auto' renders a chooser rather than guessing. Whichever venue opens, your callbacks behave identically.

iframe (phone rail)

The phone rail mounts https://app.personablocks.io/embed/:token in a full-viewport overlay iframe on your page (or inside the container you pass). The iframe carries allow="camera; microphone" so the hosted flow can reach the camera for capture.

Framing is pinned to your origin. At mint time the session records the origin of your return_url, and GET /embed/:token responds with a per-session Content-Security-Policy: frame-ancestors <your-origin> header — only that one origin may embed that one session. Any missing, expired, or malformed session falls back to X-Frame-Options: DENY, so the embed fails closed rather than open.

popup (wallet rail)

The wallet rail opens https://app.personablocks.io/verify/:token in a 480×760 popup window, giving a browser extension like MetaMask room to prompt.

Caution

Because it calls window.open(), the wallet venue’s open() must run synchronously inside a user gesture (a click handler). Call it from a setTimeout, a promise’s .then(), or on page load and the browser’s popup blocker engages — you’ll get an onError with type popup_blocked. Recover by calling redirect().

While the popup is open the SDK polls the session status. It also checks every 750 ms whether the customer closed the window by hand; if the popup disappears before a terminal status arrives, that’s treated as a cancel — onCancel fires with the resume token (your original clientToken), not an error.

redirect (fallback)

redirect() navigates the current tab to the hosted https://app.personablocks.io/verify/:token flow. It’s always available — even if you never called open() — and it’s the documented recovery path after a popup_blocked error.

You can also skip the SDK’s popup entirely: the session-mint response includes a url field pointing at that same hosted /verify/:token page, so a purely server-driven integration can just redirect the customer there.

Completion polling

The popup and redirect venues learn a session’s outcome by polling the public status endpoint, GET /api/verify-session/:token, every pollIntervalMs (default 3000). The iframe venue instead receives completion over its postMessage bridge, so it doesn’t poll.

The status response is deliberately minimized — it never carries tier, verdict, or screening data. The vic_id and method fields appear only once the session’s status is completed; on every other status they’re absent. That’s what lets onComplete deliver { sessionId, vicId, method } — IDs only.

What to read next

• SDK reference — the flow, pollIntervalMs, and error surface referenced here.
• Theming — style the flow each venue renders.