Embedded Flow Overview

What's Embedded Flow?

The embedded flow is a drop-in module that enables you to seamlessly verify individuals within your web page. It allows individuals to easily verify themselves without leaving their current experience. The flow securely collects and verifies the individual without redirecting away from your website.

The latest version of the SDK is:

There are two ways to use Embedded Flow. Both require some code:

1. Generate inquiries from an inquiry template (Minimal code required)
   • Embed the web SDK and configure it with your inquiry template ID.
   • A new inquiry is created each time a user starts the flow.
   • Best for: small numbers of users, simple use cases
   • Warning: Users who load your page multiple times will create duplicate inquiries.
2. Pre-create inquiries via API (More code required)
   • Embed the web SDK.
   • For each new user, create a new inquiry ID via API, then pass the inquiry ID to the SDK.
   • Best for: High volume and/or personalized experiences
   • Recommended for production use

Note that you can get started with the simpler implementation, and build up to the more scalable approach later.

Tutorials

• Tutorial: Embedded Flow with Inquiry Template
• Tutorial: Pre-create inquiries for Embedded Flow

Quick reference

Embed Code Snippet

Creating inquiries through the Embedded integration can be easily achieved with a short code snippet. You’ll only need your inquiry template ID which can be found in the Documentation section of your Dashboard.

1
import Persona from 'persona';
2
3
const client = new Persona.Client({
4
  templateId: "<your template ID starting with itmpl_>",
5
  referenceId: "<your reference ID for this user>",
6
  environmentId: "<your environment ID starting with env_>",
7
  onReady: () => client.open(),
8
  onComplete: ({ inquiryId, status, fields }) => {
9
    // Inquiry completed. Optionally tell your server about it.
10
    console.log('Sending finished inquiry ' + inquiryId + ' to backend');
11
  },
12
  onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
13
  onError: (error) => console.log(error),
14
});

To permit the Persona iframe to render on your domain, see Security > Embedding the Persona iframe.

Callbacks

You can also use optional callbacks for advanced Event Handling.

1
const client = new Persona.Client({
2
  templateId: "<your template ID starting with itmpl_>",
3
  environmentId: "<your environment ID starting with env_>",
4
  onReady: () => client.open(),
5
  onEvent: (name, meta) => {
6
    switch (name) {
7
      case 'start':
8
        console.log('Received event: start with inquiry ID ' + meta.inquiryId);
9
        break;
10
      default:
11
        console.log('Received event: ' + name + ' with meta: ' + JSON.stringify(meta));
12
    }
13
  }
14
});

Methods

Use the client’s Methods to show, hide, or cleanup the embedded flow widget.

1
const client = new Persona.Client({
2
	templateId: "<your template ID starting with itmpl_>",
3
  environmentId: "<your environment ID starting with env_>",
4
  onComplete: ({ inquiryId, status, fields }) => {
5
	  // Inquiry completed. Optionally tell your server about it.
6
	  console.log('Sending finished inquiry ' + inquiryId + ' to backend');
7
	  fetch('/server-handler?inquiry-id=' + inquiryId);
8
  }
9
});
10
11
function openClient() { client.open(); }
12
function cancelClient() { client.cancel(true); }