Getting Started
Looking for v3?
If your Template starts with
tmpl_
, you're onpersona@3
.We will stop supporting
persona@3
with fixes or updates on December 31, 2022. For more details about moving topersona@4
, please see migration to v4 section or contact [email protected].
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.
<!DOCTYPE html>
<html>
<head>
<!-- Fill in the appropriate version number in place of "X.Y.Z". -->
<script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js"></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: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
environment: "sandbox",
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),
});
</script>
</body>
</html>
import Persona from 'persona';
const client = new Persona.Client({
templateId: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
environment: "sandbox",
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),
});
When using the persona
NPM package, you must also ensure its peer dependencies are installed.
# npm
npm install persona react styled-components
# yarn
yarn add persona react styled-components
Testing Locally
Your local HTML must be served rather than simply opening it.
For example:
python -m http.server
open http://localhost:8000/your_html_file.html
This is due to the origin for local files (file://
) not being a valid origin for window.postMessage()
, which the Persona flow uses to communicate with your code.
Callbacks
You can also use optional callbacks for advanced Event Handling.
<!-- Fill in the appropriate version number in place of "X.Y.Z". -->
<script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js"></script>
<script>
const client = new Persona.Client({
templateId: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
environment: "sandbox",
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)}`);
}
}
});
</script>
To permit the Persona iframe to render on your domain, see Security > Embedded iframe.
If you plan on allowing the Persona flow to be opened multiple times in a window, we recommend reusing the same Persona client each time. Reusing the same iframe and listeners prevents memory leaks between clients and improves performance.
Updated about 2 years ago