Skip to content

Face SDK Web Components

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 Chrome FireFox Safari
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.iife.js';

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

  1. <face-capture></face-capture> - for creating a face snapshot;
  2. <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.iife.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,
    workerPath: 'https://your-worker-path.com',
    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. Note that if livenessType = 0 (active liveness), the button will not be displayed on mobile devices regardless of the changeCamera setting. 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
livenessType You can choose a scenario for the liveness assessment. 0 - active liveness, full process that requires head rotation; 1 - passive liveness, a person is asked to only take a selfie, no head rotation required. number 0 0, 1 face-liveness
workerPath The URL with path to your worker file. string unique regula wasm url your URL to worker face-liveness, face-capture
detectOcclusion Whether to disable face occlusion hint. boolean true true, false 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.
WEBSERVICE_NOT_COMPATIBLE The web service and component versions are incompatible.
HTTP_NOT_SUPPORTED The web component does not work over the HTTP protocol, use HTTPS instead.

The table below describes the cases of event generation:

face-liveness & face-capture

Event condition Event type Event object `event.detail` Description
The component is mounted in the DOM. `face-liveness`

`face-capture` 
{
  action: "ELEMENT_VISIBLE", 
  data: null
}
To receive this event, you must wrap the component in another element (for example, a div) and add an addEventListener to it. When the component appears in the DOM, the event will pop up. For example: 
<div id="add-event-listener-to-this-element">
  <face-liveness></face-liveness>
</div>
The "Get started" button is pressed. `face-liveness`

`face-capture` 
{
  action: "PRESS_START_BUTTON", 
  data: null
}
The "Retry" button is pressed. `face-liveness`

`face-capture` 
{
  action: "PRESS_RETRY_BUTTON", 
  data: null
}
The "Close" button is pressed. `face-liveness`

`face-capture` 
{
  action: "CLOSE", 
  data: null
}
The work of the component is completed successfully. `face-liveness`

`face-capture` 
{
  action: "PROCESS_FINISHED", 
  data: {
    response: { ... },
    status: 1
  },
}
The work of the component failed. `face-liveness`

`face-capture` 
{
  action: "PROCESS_FINISHED", 
  data: {
    reason: "An event has occurred",
    status: 0
  },
}
The work of the component finished by timeout. `face-liveness`

`face-capture` 
{
  action: "PROCESS_FINISHED", 
  data: {
    reason: "TIMEOUT_ERROR"
    status: 0
  },
}
The component is initialized and ready to work. `face-liveness`

`face-capture` 
{
  action: "SERVICE_INITIALIZED",
  data: null
}

Response

You can get the response of the component in the detail field of the event object.

For example:

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

function listener(event) {
    if (event.detail.action === 'PROCESS_FINISHED' && event.detail.data.status === 1) {
        const response = event.detail.data.response;
        console.log(response);
    }
}

component.addEventListener('face-capture', listener);

The face-liveness response has the following structure:

{
  code: number // Result codes from core lib
  metadata: {
    [key: string]: any
  };
  tag: string
  status: number // liveness status: 0 if the person's liveness is confirmed, 1 if not. 
  estimatedAge: number | null // approximate age with an accuracy of +/-3 years
  transactionId: string
  type: number // liveness type: 0 - active, 1 - passive
  images: string[] // array with the final image in base64 
}
````

The `face-capture` response has the following structure:

```javascript
{
  capture: string[] // array with the final image in base64 
}

Custom Translations

To change the standard component messages or any text, specify the language you are using (or add your own) and the label you want to change (you can see the list of available languages in the settings section, the locale setting):

Note. To see the changes, don't forget to set the language you changed to the locale setting:

const element = document.querySelector('face-liveness');

element.settings = {
    locale: 'en'
};

element.translations = {
   en: { 
     selfieTime: 'Get Selfie',
   },
};

The list of labels used in the component:

Label Default message in en locale
showOnlyOneFace Make sure there is only one face on the screen.
preparingCamera Preparing the camera...
allowAccessCamera Allow access to the camera
somethingWentWrong Something went wrong
incorrectCameraId No camera with the specified ID found.
checkCameraId Check if the specified camera ID is correct.
preparingService Preparing the service...
allowAccessToCamera Allow access to the camera and reload this page to continue.
error Error!
versionNotSupported Your browser version is not supported.
updateBrowser Update your browser version
licenseError A license error has occurred
licenseExpired The license cannot be found or has expired
onlyPortraitOrientation Portrait orientation only
turnDeviceIntoPortrait Please turn your device into portrait mode
tryAgain Try again
noCameraAvailable No camera available
checkCameraConnection Check the camera connection and try again.
lookStraight Look straight
fitYourFace Center your face
moveCloser Move closer
moveAway Move away
holdSteady Hold steady
processing Processing...
retryButtonText Retry
followGuidelinesText But please follow these guidelines:
letsTryAgainTitle Let’s try that again
noCameraPermission Camera unavailable!
goButton Go
selfieTime Selfie time!
ambientLighting Ambient lighting is not too bright or too dark and there are no shadows or glare on your face
noMaskSunglassesHeaddress Neutral facial expression (no smiling, eyes open and mouth closed), no mask, sunglasses or headwear
turnHead Turn your head a bit
centerFaceTurnHead Center your face, turn your head
centerFace Center your face
errorCode Error code:
illumination Good illumination.
cameraLevel Camera at eye level.
noAccessories No accessories: glasses, mask, hat, etc.
getReady Get ready
removeOcclusion Remove items covering your face

Examples

You can find examples of using the components on the Samples page.

Licensing

The Face SDK Web Components do not require licensing. A license is only needed for the Face SDK Web Service.

Additional Resources

The Face SDK Web Components are also available on Storybook.