iFrame integration Guide

This guide will help you to integrate your Web Flow in your website.

What is an iFrame?

According to MDN docs: The <iframe> HTML element represents a nested browsing context, embedding another HTML page into the current one.

iFrame integration

NOTE: Before proceeding, make sure you have set up an account and created your Truora API Key.

The following steps will help you consume our Digital Identity services through Iframe, which will allow you to integrate a web flow in your website:

Create Web Flow: follow the guide to Create a Web Flow using our flow builder.

NOTE: Within the flow builder, you can customize your web flow to change its look and feel, as well as brand it according to your preferences.

Once the flow has been created and tested, go to My Flows in the platform to identify the flow id, which will be required in the next steps.

Create an Account ID: The account identifies the users in Truora’s system, and it is represented by the account_id, which is a unique value assigned to each user in the system to distinguish them and access their information and processes. Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
Create a Process Link: After creating a web flow and acquiring the account ID, follow these steps:
- Get a Web Integration Token
  - NOTE: A token must be generated each time you want to perform a new validation for a user.
- Use the obtained Web Integration Token to generate the Process Link
- The Process Link will link your flow to a URL, enabling you to perform validations.

Follow the instructions in Create a Process Link to learn how to do it. The created Process Link should look something like this:

`https://identity.truora.com/?token=<api_key>`

NOTE:

Please be aware that Truora API Key is different from the api_key token (Web Integration Token) in your Process Link.
The Web Integration Tokens have a 2 hours shelf life by default.

Include the iFrame tag within the HTML page where you want to visualize our flow:

html


  <iframe
  src="https://identity.truora.com/?token=api_key"
  allow="camera"
  width=".. px"
  height=".. px">
  </iframe>

Replace:

src with the Process Link created in the previous step.
width and height with the desired values in pixels.

NOTE:

Adding the allow=“camera” attribute allows the user to use the camera to take a picture of the document.
Before you embed the iFrame in your site, you must have your application registered in Truora, this means let our team know the URL where you are going to embed the iFrame. If you don’t have your application registered yet, please contact your integration manager and give them this information or contact us through WhatsApp

.

PostMessage (Advanced)

Disclaimer: This configuration requires an understanding of JavaScript listeners, so we recommend you have a developer or tech-savvy person do or help during this process

When integrating through iFrame, you may receive one of the following three messages when the web identity process has finished:

truora.process.succeeded → Indicates a final status of success after the process steps have finished.
truora.process.failed → Indicates a final status of failure after the process steps have finished.
truora.steps.completed → Indicates that there is still no final status of success or failure after the process steps have finished. This could occur because there are asynchronous steps in the process, such as document or face validation.

When is this message sent?

The message is sent when the user clicks on “Finish validation” or when a redirection is triggered (if the button is not clicked within 3 seconds after the completion message appears):

How can you obtain the message?

To obtain the message, you need to include a listener in your JavaScript code. Here’s an example of how you can do it:

postMessage


  window.addEventListener("message", (event) => {
    // Handle the received message, which can be accessed via event.data
    // For more information, refer to: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
  });

Note: For precise control over the received messages, we recommend including the Get Validations Result step when you are Creating your Web Flow. This ensures that you receive only the succeeded or failed messages, allowing for better handling and management of the validation process:

Get Results

The process results can be obtained in two ways:

Polling: You can get the process (or flow) results with a query to Truora’s API or from the dashboard. For more information, please see the Guide to Get Results.
Webhooks: You can get automatic notifications about Results from a user, for which you must subscribe Webhooks. This alternative allows you to receive hooks of actions/rules you created. For more information please visit Webhooks guide.

Security considerations

The iFrame integration is a secure way to integrate in your website. However, you must take into account the following security considerations:

Review your Content Security Policy (CSP).
Employ defensive code in the UI to ensure that the current frame is the most top level window.
Properly set authentication cookies with SameSite=Strict (or Lax) and Secure flags.

We strongly recommend you to review the following resources to learn more about security considerations when using iFrames:

Was this helpful?