JavaScript SDK

The purpose of the JS SDK is to create the session URL for your end-user's verification session.

Veriff JS SDK is a simple and customizable library, making it a convenient way to include Veriff's web flow to your solution.

Once you have the session URL, you have two options to direct the user to the verification flow:

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)


Add SDK to the project

Step 1: Install the JS SDK

Either as a script tag

<script src='https://cdn.veriff.me/sdk/js/1.5/veriff.min.js'></script>

Or, via package manager:

$ npm install --save @veriff/js-sdk

// CommonJS
  const Veriff = require('@veriff/js-sdk');

// ES6 style import
import { Veriff } from '@veriff/js-sdk';

Step 2: Add the JS SDK

Add a parent element in HTML

<div id='veriff-root'></div>

It is possible to set the width of js-sdk form through style attribute:

<div id='veriff-root' style="width:400px"></div>

Step 3: Add viewport meta tag

The viewport meta tag is crucial for proper rendering and layout on mobile devices. If this meta tag is missing, the website may be rendered too small on mobile devices.

Make sure to add the following tag to mitigate such issues:

<meta name="viewport" content="width=device-width, initial-scale=1.0">


Start the verification flow

Initialize the library and define what happens when a verification session is started.

In order to initialize the library, you need the following functions: API Key, parentId and onSession callback function.

Functions are defined as below.

Function

Description

apiKey*

This is your integration’s API key. See the API Documentation and reference[↗] for instructions where to find the integrations API key

parentId*

Value is veriff-root

onSession*

Defines what happens when the verification session is started:

* Required parameter

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started / triggered now

      // redirect
      window.location.href = response.verification.url;

      // incontext sdk
      createVeriffFrame({url: response.verification.url});
    }
  });

  veriff.mount();

With this, three things are happening:

  1. A front-end view of the verification session is generated, which will allow the end-user to enter their data and get verified

  2. In the back, an API call is made

  3. Once the API response is received, the onSessions function is executed

The front-end view

In the front-end, the end-user will see the following:

The end-user needs to fill in the input fields and press the button to start the verification session.

It is possible to customize the front-end web flow text fields and the text on the button. It is also possible to remove all input fields from the view. See the Customize the SDK section below for more info.

The API call

The response body contains a verification object with following schema:

    {
      "status": "success",
      "verification": {
          "id": "UUID V4 identifying the verification",
          "url": "full url to which a person should be redirected in order to proceed with verification flow",
          "host": "hostname",
          "status": "status of the verification",
          "sessionToken": "JWT encoded verification token"
      }
  }

The onSession function

It is executed after the response has been received from the API call (see the section above).

  1. If you decide to redirect the end-user to the verification flow, see the Redirection Guide for more info

  2. If you decide to use Veriff’s modal based approach, see the InContext SDK section for more info


Customize the SDK

SDK customization is optional

It is possible to customize the fields of the verification web view flow that is shown to the end-user.

Customize input fields and the launch button

The text values of the input fields and the button can be customized:

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.mount({
    formLabel: {
      givenName: 'First name',
      lastName: 'Family name',
      vendorData: 'Unique id of an end-user'
    },
    submitBtnText: 'START YOUR SESSION',
    loadingText: 'Please wait...'
  });

With such values, the following prompt is rendered:

Disable input fields

It is possible to disable the rendering of input fields (so that the end-users themselves do not need to pass any data) by not including anything in the corresponding values:

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.setParams({
    person: {
      givenName: ' ',
      lastName: ' '
    },
    vendorData: ' '
  });
  veriff.mount({
    submitBtnText: 'Get verified'
  });

With such values, the following prompt is rendered:

Pass data yourself and disable input fields

In case the givenName or lastName or vendorData or all of them are known, they can be passed to the SDK, therefore the text input fields will not be rendered.

const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.setParams({
    person: {
      givenName: 'Foo',
      lastName: 'Bar'
    },
    vendorData: '7eb19312-79d6-11ec-90d6-0242ac120003'
  });
  veriff.mount({
    submitBtnText: 'Get verified'
  });

With such values, the following prompt is rendered: