Getting Started

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.

Quickstarts

• Quickstart: Embedded Flow with Inquiry Template
• Quickstart: 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); }