@regulaforensics/vp-frontend-face-components-beta

Face SDK Web Components

Overview
Before You Start
Compatibility
Install via NPM
Install via CDN
Settings
Customization
Events
Response
Custom translations
Examples
Additional resources

Overview

The Face SDK Web Components let you add automatic capture of a user's selfie and liveness check to your web site. The components capture a face from the device camera and can either simply detect a face on the captured photo or confirm the face liveness.

The available components are the following:

face-capture
face-liveness

The Web Components are based on WebAssembly (.wasm module), which is our core C++ code compiled for use in browsers and wrapped with a JS layer. It is exactly the same code as built for all the other platform SDK packages.

Before You Start

Important notes:

The Face SDK Web Components and their methods strictly require secure contexts, so using the HTTPS protocol is a must.
The considered components are registered on the web page itself, so make sure to import the library to your website before adding any of the components to the web page code.
Only the modern browser versions are supported, see compatibility. Polyfills are not included in the package by default.

Compatibility

Devices
Mobile (iOS)	99 (iOS14.4+)	99 (iOS14.4+)	11
Mobile (Android)	69	63	-
Desktop	66	69	11

To support the older browser versions in your project, install the required polyfill packages manually. Follow the link to an npm package @webcomponents/webcomponentsjs for installation details.

Install via NPM

On the command line, navigate to the root directory of your project:

cd /path/to/project

Run the following command:

npm init

Answer the questions in the command line questionnaire.

Install @regulaforensics/vp-frontend-face-components:

npm i @regulaforensics/vp-frontend-face-components

Create index.html and index.js files in the root directory of the project.

Import @regulaforensics/vp-frontend-face-components into your index.js:

import './node_modules/@regulaforensics/vp-frontend-face-components/dist/main.js';

In index.html connect index.js and add the name of the component you want to use. Available components:

<face-capture></face-capture> - for creating a face snapshot;
<face-liveness></face-liveness> - for performing liveness verification.

For example:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My app</title>
  </head>
  <body>
    <face-capture></face-capture>
    <script type="module" src="index.js"></script>
  </body>
</html>

Install via CDN

Connect the script in your .html file. CDN link: unpkg.com/:package@:version/:file

For example:

<script src="https://unpkg.com/@regulaforensics/vp-frontend-face-components@latest/dist/main.js"></script>

Add the name of the component to the html, as in the example above.

Settings

Note that we have removed the videoRecording setting. Now you should use recordingProcess instead.

You can set any parameter using settings. Find below examples of applying all the settings at once as well as using just some of them.

An example of using all the settings:

const component = document.getElementsByTagName('face-liveness')[0];

component.settings = {
    locale: 'en',
    copyright: true,
    cameraId: '123',
    changeCamera: true,
    startScreen: true,
    closeDisabled: true,
    finishScreen: true,
    url: 'https://your-server.com',
    headers: {
        Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
    },
    tag: 'sessionIdValue',
    retryCount: 5,
    recordingProcess: 1,
    customization: {
        fontFamily: 'Noto Sans, sans-serif',
        fontSize: '16px',
        onboardingScreenStartButtonBackground: '#7E57C5',
        onboardingScreenStartButtonBackgroundHover: '#7c45b4',
        onboardingScreenStartButtonTitle: '#FFFFFF',
        onboardingScreenStartButtonTitleHover: '#FFFFFF',
        cameraScreenFrontHintLabelBackground: '#E8E8E8',
        onboardingScreenIllumination: 'https://path-to-image.com',
        onboardingScreenAccessories: 'data:image/svg+xml;base64,PHN2...',
        onboardingScreenCameraLevel: importedImage,
        cameraScreenFrontHintLabelText: '#000000',
        cameraScreenSectorActive: '#7E57C5',
        cameraScreenSectorTarget: '#BEABE2',
        cameraScreenStrokeNormal: '#7E57C5',
        processingScreenProgress: '#7E57C5',
        retryScreenRetryButtonBackground: '#7E57C5',
        retryScreenRetryButtonBackgroundHover: '#7c45b4',
        retryScreenRetryButtonTitle: '#FFFFFF',
        retryScreenRetryButtonTitleHover: '#FFFFFF',
        retryScreenEnvironmentImage: 'https://path-to-image.com',
        retryScreenPersonImage: 'data:image/svg+xml;base64,PHN2...',
        successScreenImage: importedImage,
    }
}

An example of using just the selected settings:

const yourSettings = {
    locale: 'de',
    videoRecording: false,
    url: 'https://your-server.com',
    headers: {
        Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
    },
    customization: {
        fontFamily: 'Noto Sans, sans-serif',
        successScreenImage: importedImage,
    }
}

const component = document.getElementsByTagName('face-liveness')[0];

component.settings = yourSettings;

Here are all the available settings:

Setting	Info	Data type	Default value	Values	Used in
`locale`	Language of the component.	`string`	`en`	`ru`, `en`, `de`, `pl`, `it`, `hu`, `zh`, `sk`, `uk`, `fr`, `es`, `pt`, `ar`, `nl`, `id`, `vi`, `ko`, `ms`, `ro`, `el`, `tr`, `ja`, `cs`, `th`, `hi`, `bn`, `he`, `fi`, `sv`, `da`, `hr`, `no`	`face-liveness`, `face-capture`
`url`	Backend URL.	`string`	`https://faceapi.regulaforensics.com/`	any url	`face-liveness`
`copyright`	Whether to show the Regula copyright footer.	`boolean`	`false`	`true`, `false`	`face-liveness`, `face-capture`
`cameraId`	Ability to select a camera by defining the camera ID.	`string`	`undefined`	`camera id string value`	`face-liveness`, `face-capture`
`changeCamera`	Whether to show the "Camera Switch" button.	`boolean`	`true`	`true`, `false`	`face-liveness`, `face-capture`
`startScreen`	Whether to show the Start screen with video instructions. If `true`, the start screen is shown. If `false`, no start screen is shown and instead the camera of the device is turned on automatically to capture a face.	`boolean`	`true`	`true`, `false`	`face-liveness`, `face-capture`
`finishScreen`	Whether to show the Result screen (`success screen`, `retry-screen`). If `true`, the Result screen is shown to the user. If `false`, no Result screen is displayed, and, during a single session, the user has only one attempt to pass liveness assessment. In cases where `finishScreen` is set to `false`, we recommend to monitor Events associated with the liveness assessment and then display relevant information to the user based on those events. This approach ensures that the user receives necessary feedback even though the Result screen is not displayed by the component itself.	`boolean`	`true`	`true`, `false`	`face-liveness`, `face-capture`
`closeDisabled`	Whether to disable the "Close" button of the component. If set to `true`, the "Close" button is hidden from the user.	`boolean`	`false`	`true`, `false`	`face-liveness`, `face-capture`
`recordingProcess`	Whether to enable a video recording of the process. If set to `0`, the video is sent to the server with an additional request. If set to `1`, the video is sent to the server with the liveness package. If set to `2`, the video isn't sent. The video format depends on the browser: MP4 for Safari, WEB for other browsers.	`number`	`0`	`0`, `1`, `2`	`face-liveness`
`tag`	The server generates a unique identifier for each session before starting a verification process. Using `tag`, you can set a custom value. Make sure that `tag` is unique for each session.	`string`	`undefined`	any unique for each session	`face-liveness`
`retryCount`	Using the `retryCount` setter, you can set the number of liveness transaction attempts for the user. Once the attempts are exhausted, the component will display a white screen and throw the "RETRY_COUNTER_EXCEEDED" event. By default, the number of attempts is unlimited. Setting the value to 0 removes the limit on the number of attempts, while any positive number limits the attempts.	`number`	`-1`	number of the attempts count	`face-liveness`
`headers`	Before starting the camera capture, the component sends a `start` request to the server and receives the initialization data in response. Once the component successfully completes two stages of verification, it sends the received data to the API for processing. You can use the `headers` setter to set the headers for the HTTP POST method. Additionally, the video recording is transmitted to the server along with these `headers`.	`object`	`undefined`	object with headers (key, value).	`face-liveness`
`customization`	You can customize the element's color, font, and image by using this object. See the Customization section below.	`object`	`undefined`	object with customization settings	`face-liveness`, `face-capture`
`nonce`	You can set a unique nonce value to maintain the CSP policy.	`string`	`undefined`	unique nonce value	`face-liveness`, `face-capture`
`rotationAngle`	Desktop only. By using the `rotationAngle` setter, you can specify an angle to compensate for the rotation of your physical camera. When set to values of `90` and `-90`, the component's design will switch to a mobile (vertical) orientation.	`number`	`undefined`	`0`,`180`,`90`,`-90`	`face-liveness`, `face-capture`
`holdStillDuration`	For the Capture screen, sets the duration that the user needs to stand straight and look in the camera.	`number`	`undefined`	seconds	`face-capture`
`timeoutInterval`	Timeout for the Capture screen.	`number`	`undefined`	seconds	`face-capture`

Customization

You can customize the color of some elements, fonts, and images with the help of the customization field in the settings object. The customization settings are the following:

Setting	Info	Migrate from	Data type	Default value
`fontFamily`	Font.	`--font-family`	string	`Noto Sans, sans-serif`
`fontSize`	Base font size.	`--font-size`	string	`16px`
`onboardingScreenStartButtonBackground`	Instruction screen button background color.	`--main-color`	string	`#7E57C5`
`onboardingScreenStartButtonBackgroundHover`	Instruction screen button background hover color.	`--hover-color`	string	`#7C45B4`
`onboardingScreenStartButtonTitle`	Instruction screen button text color.		string	`#FFFFFF`
`onboardingScreenStartButtonTitleHover`	Instruction screen button text hover color.		string	`#FFFFFF`
`onboardingScreenIllumination`	Instruction screen "Illumination" icon image.		base64 or url or imported image
`onboardingScreenAccessories`	Instruction screen "No accessories" icon image.		base64 or url or imported image
`onboardingScreenCameraLevel`	Instruction screen "Camera level" icon image.		base64 or url or imported image
`cameraScreenFrontHintLabelBackground`	Сamera screen plate with info message background color.	`--plate-color`	string	`#E8E8E8`
`cameraScreenFrontHintLabelText`	Сamera screen plate with info message text color.		string	`#000000`
`cameraScreenSectorActive`	User progress sector color (available only in face-liveness component).		string	`#7E57C5`
`cameraScreenSectorTarget`	Target sector color (available only in face-liveness component).	`--target-sector-color`	string	`#BEABE2`
`cameraScreenStrokeNormal`	Stroke color of the camera circle.		string	`#7E57C5`
`processingScreenProgress`	Processing screen spinner color.		string	`#7E57C5`
`retryScreenEnvironmentImage`	Retry screen environment image.		base64 or url or imported image
`retryScreenPersonImage`	Retry screen person image.		base64 or url or imported image
`retryScreenRetryButtonBackground`	Retry screen button background color.	`--main-color`	string	`#7E57C5`
`retryScreenRetryButtonBackgroundHover`	Retry screen button background hover color.	`--hover-color`	string	`#7C45B4`
`retryScreenRetryButtonTitle`	Retry screen button text color.		string	`#FFFFFF`
`retryScreenRetryButtonTitleHover`	Retry screen button text hover color.		string	`#FFFFFF`
`successScreenImage`	Success screen image.		base64 or url or imported image

For example:

const component = document.getElementsByTagName('face-liveness')[0]; 

component.settings = {
    ...otherSettings,
    customization: {
        fontFamily: 'Noto Sans, sans-serif',
        fontSize: '16px',
        onboardingScreenStartButtonBackground: '#7E57C5',
        onboardingScreenStartButtonBackgroundHover: '#7c45b4',
        retryScreenPersonImage: 'data:image/svg+xml;base64,PHN2...',
    }
}

Events

You can subscribe to the component events.

For example:

const faceLivenessComponent = document.getElementsByTagName('face-liveness')[0]; 
const faceCaptureComponent = document.getElementsByTagName('face-capture')[0];

faceLivenessComponent.addEventListener('face-liveness', (event) => console.log(event.detail)); // event listener for face-liveness component
faceCaptureComponent.addEventListener('face-capture', (event) => console.log(event.detail)); // event listener for face-capture component

The face-liveness type of event is generated for the face-liveness component, and face-capture type of event is generated for the face-capture component.

The generated event object (event.detail) contains three fields that describe the event:

{
  action: "PRESS_START_BUTTON", // the type of action that generated the event (all actions are described in the table below)
  data: null, // component data
  manual: true // event generated by user action or component by itself
}

Type of actions:

Type of action	Description of the action	The component
`ELEMENT_VISIBLE`	The component is appended in the DOM.	`face-liveness`, `face-capture`
`PRESS_START_BUTTON`	The "Get started" button is pressed.	`face-liveness`, `face-capture`
`PRESS_RETRY_BUTTON`	The "Retry" button is pressed.	`face-liveness`, `face-capture`
`CLOSE`	The "Close" button is pressed.	`face-liveness`, `face-capture`
`PROCESS_FINISHED`	The component has finished its work.	`face-liveness`, `face-capture`
`SERVICE_INITIALIZED`	The component has started its work.	`face-liveness`, `face-capture`
`RETRY_COUNTER_EXCEEDED`	The component has finished its work due to the exceeded number of transaction attempts.	`face-liveness`

In cases of successful operation of the components, the data field will contain the following fields:

{
  response: { ... }, // component result
  status: 1 // 1 for successful work and 0 for unsuccessful
}

In cases of unsuccessful work, the data field will contain the following fields:

{
  reason: "CAMERA_PERMISSION_DENIED", // error reason (possible causes of errors are described in the table below)
  status: 0
}

Table of event causes:

Reason	Description of the reason
`WASM_ERROR`	Error in WASM.
`UNKNOWN_ERROR`	Unknown error.
`NOT_SUPPORTED`	The browser is not supported.
`CAMERA_UNKNOWN_ERROR`	Unknown camera error.
`CAMERA_PERMISSION_DENIED`	Access to the camera is prohibited.
`NO_CAMERA`	There is no camera.
`INCORRECT_CAMERA_ID`	There is no camera available.
`CONNECTION_ERROR`	Connection errors.
`LANDSCAPE_MODE_RESTRICTED`	Work in landscape orientation is prohibited.
`TIMEOUT_ERROR`	Transaction failed due to timeout.
`CHANGE_CAMERA`	The user has changed the camera. Return to start-screen or restart service if start-screen is disabled.
`DEVICE_ROTATE`	The user has rotated the device. Return to start-screen or restart service if start-screen is disabled.
`APP_INACTIVE`	The user has closed the tab or browser during the face capture process.
`INCORRECT_CAMERA_ID`	No camera with the specified ID found.

The table below describes the cases of event generation: