Embedded Widget

The Embedded Widget is a client-side integration method. It renders the user-facing verification directly in your website and invokes a callback when the flow finishes. No PII is returned to your client.

Prerequisites

Before rendering the Widget, your server must create a Relay session and return the Relay session access token to your web client. See server-side integration methods.

Embed 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 render.

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

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

1
// A CSS selector that targets the element with id="relay-container"
2
new Relay("#relay-container", options);
3
4
// A DOM element, such as a React ref
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
  theme: "auto", // 'light' | 'dark' | 'auto' (default: 'auto')
6
  onComplete: () => {
7
    // Ask your server to retrieve the claim result.
8
  },
9
  onExpire: () => {
10
    // The Relay session expires after 30 minutes.
11
    // Create a new Relay session on your server, then initialize again.
12
  },
13
  onError: (error) => {
14
    console.error(error);
15
  },
16
});

During this step:

• The Widget renders the configured verification experience.
• The user completes the flow inside the Widget.
• onComplete signals that the user-facing flow finished. It does not return PII or the claim result.

When onComplete runs, ask your server to retrieve the claim result with the Relay token, Relay secret, and Privacy Pass token stored during the server-side phases. See server-side integration methods.

Cleanup

Call relay.destroy() to unmount the Widget and clean up resources when it is no longer needed.