Getting Started

The latest version of the SDK is:

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 Integration section of your Dashboard.

import Persona from 'persona';

const client = new Persona.Client({
  templateId: "<your template ID starting with itmpl_>",
  referenceId: "<your reference ID for this user>",
  environmentId: "<your environment ID starting with env_>",
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    // Inquiry completed. Optionally tell your server about it.
    console.log(`Sending finished inquiry ${inquiryId} to backend`);
  },
  onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
  onError: (error) => console.log(error),
});

<!DOCTYPE html>
<html>
  <head>
    <!-- Replace "X.Y.Z" with the Inquiry SDK version you want to use. -->
    <!-- 
        It's best practice to provide an integrity attribute. 
        Learn more here: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
        Or copy the code snippet from the Persona dashboard, which provides the hash for you.
    -->
    <script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js" integrity="your-integrity-hash" crossorigin="anonymous"></script>

    <!-- charset and viewport meta tags are required! -->
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>

  <body>
    <!-- Initialize the Persona client in whichever way is appropriate for your application. -->
    <script>
      const client = new Persona.Client({
        templateId: "<your template ID starting with itmpl_>",
        referenceId: "<your reference ID for this user>",
        environmentId: "<your environment ID starting with env_>",
        onReady: () => client.open(),
        onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
        onError: (error) => console.log(error),
        onEvent: (name, metadata) => {
          if (name === 'start') {
            // Collect and save the inquiry ID for future use
            inquiryId = metadata["inquiryId"]
          }
        },
        onComplete: ({ inquiryId, status, fields }) => {
          // Inquiry completed. Optionally tell your server about it.
          console.log(`Sending finished inquiry ${inquiryId} to backend`);
          // Optionally, cleanup the client to avoid memory leaks.
          // client.destroy();
        },
      });
    </script>
  </body>
</html>

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.

const client = new Persona.Client({
  templateId: "<your template ID starting with itmpl_>",
  environmentId: "<your environment ID starting with env_>",
  onReady: () => client.open(),
  onEvent: (name, meta) => {
    switch (name) {
      case 'start':
        console.log(`Received event: start with inquiry ID ${meta.inquiryId}`);
        break;
      default:
        console.log(`Received event: ${name} with meta: ${JSON.stringify(meta)}`);
    }
  }
});

Methods

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

const client = new Persona.Client({
	templateId: "<your template ID starting with itmpl_>",
  environmentId: "<your environment ID starting with env_>",
  onComplete: ({ inquiryId, status, fields }) => {
	  // Inquiry completed. Optionally tell your server about it.
	  console.log(`Sending finished inquiry ${inquiryId} to backend`);
	  fetch(`/server-handler?inquiry-id=${inquiryId}`);
  }
});

function openClient() { client.open(); }
function cancelClient() { client.cancel(true); }