Widget

The Relay widget handles the entire user-facing verification experience — government ID capture, selfie, and any other configured steps. No PII is returned to your frontend; the widget only surfaces a completion signal.

Prerequisites

Before rendering the widget, your server must have already created a Relay session and returned a relay-session-access-token to your frontend. See the server-side integration methods for how to do this.

Rendering the widget

Install

Available on npm: @persona/relay

$
npm install @persona/relay

Add a container element

Add a div to your HTML where the widget will be rendered.

1
<div id="relay-container"></div>

The first argument accepts either a CSS selector string or a direct DOM element reference:

1
// CSS selector — targets the DOM element with id="relay-container"
2
new Relay('#relay-container', options);
3
4
// DOM element (e.g. in React)
5
new Relay(containerRef.current, options);

Initialize

1
import Relay from '@persona/relay';
2
3
const relay = new Relay('#relay-container', {
4
  accessToken: '<relay-session-access-token from your server>',
5
  onComplete: () => {
6
    // Verification done — trigger your server to retrieve the claim result
7
  },
8
  onExpire: async () => {
9
    // Session expired (30 min limit) — fetch a new session from your server and re-initialize
10
  },
11
  onError: (error) => {
12
    console.error(error);
13
  },
14
});

During this step:

• The widget renders the configured verification experience (e.g. government ID + selfie)
• The user completes the flow entirely within the widget
• No PII is returned to your frontend — onComplete only signals that verification is done

Once onComplete fires, retrieve the claim result from your server using the relay token and relay secret obtained during session creation.

Cleanup

Call client.destroy() to unmount the widget and clean up resources when it’s no longer needed.