InContext SDK

Updated
  • Updated on May 15, 2025
  • Published on May 30, 2024
Prev Next

Veriff InContext solution allows your end-users to go through the verification process within your web page, maintaining uninterrupted workflow and reducing friction.

→ If you are interested in implementing Veriff’s verification flow using WebViews, see Embedding in Android and iOS WebViews

Requirements and prerequisites

Prerequisites

  • You have an active account with Veriff (see the Getting Started section)

  • You have an integration with Veriff (see the Getting Started section)

  • You have set up webhook(s) to get replies from Veriff (see the Webhooks section)

  • You have integrated a solution that allows you to create session URLs for your end-users (using the API POST /sessions[↗] call or Javascript SDK)

Add SDK to the project

Step 1: Install InContext SDK

npm install @veriff/incontext-sdk

Step 2: Create a session URL

You need to have a Veriff session URL generated before initializing the SDK.

You have two options:

  • see the POST /sessions[↗] in API documentation to learn how to generate a session URL via API call

  • use the JavaScript SDK to create the session URL

Step 3: Initialize the SDK

You have three options: using iFrame, inline script or embedded mode.

Using with iFrame

The snippet below will render a modal with adapted Veriff application in iFrame.

createVeriffFrame() returns an object that controls the modal.

// CommonJS
const { createVeriffFrame } = require('@veriff/incontext-sdk');

// ES6
import { createVeriffFrame } from '@veriff/incontext-sdk';

const veriffFrame = createVeriffFrame({ url: VERIFF_SESSION_URL })

Using the inline script

Include a script tag

<script src='https://cdn.veriff.me/incontext/js/v1/veriff.js'></script>

window.veriffSDK.createVeriffFrame({ url: VERIFF_SESSION_URL });

Using the embedded mode

Before using embedded mode, make sure the incontext_sdk_embedded_allowed feature flag is enabled for your account.

Contact your solutions engineer for info and configuration.

The embedded mode allows you to inject the Veriff flow to a specific part of your website, without a modal. To enable embedded mode, set the embedded option to true.

Note about dimensions

  • Minimum 600x680 width/height

  • Optimal 800x800 width/height

The flow will render regardless of the dimensions, but the user experience might be affected.

Example

const veriffFrame = createVeriffFrame({
  url: VERIFF_SESSION_URL 
  embedded: true,
  embeddedOptions: {
    // Specifies the parent DOM element of Veriff’s iframe, using its ID attribute
    rootElementID: 'embedded-container',
  },
});

<div
  style={{ width: '635px', height: '670px', border: '1px solid #ccc' }}
  id="embedded-container"
/>

Add permissions

Content Security Policy

In order to improve security, add the following CSP directives headers to index.html file, under the <meta> tag:

Content-Security-Policy default-src 'self' *.veriff.me *.veriff.com;
script-src 'self' *.veriff.me *.veriff.com *.hotjar.com *.probity.io;
img-src blob: 'self' *.probity.io;
frame-src 'self' *.hotjar.com;
connect-src 'self' *.veriff.com *.veriff.me *.probity.io;
style-src 'self' *.veriff.com *.veriff.me;

For example:

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-security-policy"
 content="default-src 'self' *.veriff.me *.veriff.com;
script-src 'self' *.veriff.me *.veriff.com *.hotjar.com *.probity.io;
img-src blob: 'self' *.probity.io;
frame-src 'self' *.hotjar.com;
connect-src 'self' *.veriff.com *.veriff.me *.probity.io;
style-src 'self' *.veriff.com *.veriff.me;">
</head>

Camera access

To avoid any issues, make sure that you allow Veriff to request camera access. If your Permissions Policy denies camera requests by default, you may encounter issues when using the InContext SDK. For more information, please read the W3C Permissions Policy Explainer[↗] .

Start the verification flow

You need to pass the sessionURL from the verification session that you started with either POST /sessions[↗] API call or using the JavaScript SDK.

Step 1: create a session

You have two options to create a session:

  1. Use the POST /sessions[↗]  public API call

  2. Use Veriff’s JavaScript SDK to start a session

In order to start a session, you need to find your API keys and the base URL. See the API Documentation and reference[↗] article in the Veriff API documentation.

The minimum contents of the POST /sessions request is:

{"verification": {
        "callback": "https://veriff.com",
        "vendorData": "11111111"
    }
}

Note that even the vendorData field is optional. Nonetheless, Veriff strongly recommends you create and store end-user IDs for your end-users, and pass those to Veriff using the vendorData parameter. See the Glossary for more info about the vendorData.

Step 2: pass the sessionURL

Use the following function:

const veriffFrame: const veriffFrame = createVeriffFrame({ url: VERIFF_SESSION_URL })

What happens after the end-user leaves the flow?

When the end-user leaves the verification flow, i.e. a session is canceled or finished, the Veriff SDK is closed. The end-user is taken back to your application. The end-user flow completion status is returned to the host application, see Verification session status section below for more info.

Verification session status

When a session is cancelled or finished, the InContext SDK emits the CANCELED or FINISHED events. It is up to you to decide what happens (close, redirect) in the SDK when the events are triggered.

You can capture the end-user flow status, to do this, pass onEvent callback function when initializing the SDK.

This is not the verification session decision.

This indicates whether the end-user was able to complete all the steps in the verification flow or not.

import { createVeriffFrame, MESSAGES } from '@veriff/incontext-sdk';

createVeriffFrame({
  url: VERIFF_SESSION_URL 
  onEvent: function (msg: MESSAGES) {
    switch (msg) {
      case MESSAGES.STARTED:
        console.log('Verification started');
        break;
      case MESSAGES.SUBMITTED:
        console.log('Verification submitted');
        break;
      case MESSAGES.FINISHED:
        console.log('Verification finished');
        break;
      case MESSAGES.CANCELED:
        console.log('Verification closed');
        break;
      case MESSAGES.RELOAD_REQUEST:
        console.log('Verification reloaded');
        break;
    }
  },
});

In the example above, the CANCELED message was emitted. Options are:

  • STARTED - indicating that the session status has been changed to started

  • FINISHED - indicating that the end-user completed the verification flow and closed the modal

  • CANCELED - indicating that the end-user abandoned the verification flow and closed the modal

Verification session decision

Veriff returns info about the verification session decision, extracted data, registries checks etc via webhooks. You need to set up webhooks and tie them to your system.

→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process

Customize the SDK

SDK customization is optional

It is possible to configure a number of elements with the following function:

createVeriffFrame([options])

The [options] can be replaced with following functions to customize the SDK:

  • url*- specify the verification session URL

  • lang - set the user interface language to a supported language

  • onEvent - specify what happens when the onEvent function is triggered

  • onReload - set up the onReload request callback to handle webpage reloading and SDK reopening

  • embedded - set to true if you want to use embedded mode

  • embeddedOptions - embedded mode options

  • rootElementID - specifies the parent document object model (DOM) element of Veriff’s iframe, using its ID attribute

*Required

Define onReload function

This is an edge case for Safari iOS to re-request camera permissions, to handle the situation when the end-user has denied camera access and now the access to the host page needs to be requested again and the page needs to be reloaded again.

const url = sessionStorage.getItem('@veriff-session-url') || getSessionUrl()

veriffSDK.createVeriffFrame({
  url,
  onReload: () => {
    // Logic to re-open Veriff SDK after page reload
    // e.g. sessionStorage.setItem('@veriff-session-url', url);
    window.location.reload();
  },
});

Define .close() function for Veriff modal

Normally, the Veriff end-user view (modal) is closed according to the end-user input, but you can use the function below to control it (e.g. set up timeout):

veriffFrame.close();

Article versioning

Date

Description

May 15, 2025

Link to Embedding in Android and iOS WebViews added

Mar 28, 2025

Broken link fixed

Mar 12, 2025

Documentation published

Related articles