Skip to content

Face Web Components

Overview

The Face 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:

  • face-сapture
  • face-liveness

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

Before you start

Please note that:

  • The components work only under the HTTPS protocol on the web site.
  • The components library does register the components on the web page itself, so make sure to import the library to your web site before adding the components to the web page code.

Compatibility

Devices Chrome FireFox Safari
Mobile (iOS) 99 (iOS14.4+) 99 (iOS14.4+) 11
Mobile (Android) 66 62 -
Desktop 66 63 11

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:

  1. <face-capture></face-capture> - for a face snapshot;
  2. <face-liveness></face-liveness> - for liveness verification.

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

Example:

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

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

Settings

face-liveness

The server generates a unique identifier for each session before starting a verification process. Using sessionId setter you can set custom value. Make sure that the sessionId is unique for each session

Example:

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

component.sessionId = "ID"

After passing two stages of verification, the component sends the received data for processing to the API. Using headers setter you can set HTTP POST method headers.

Example:

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

component.headers = {
    Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
}

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 In which component is present
ELEMENT_VISIBLE 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

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 error causes:

Reason Description of the reason
WASM_ERROR Error in WASM.
WASM_LICENSE Missing or incorrect license.
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.
CONNECTION_ERROR Connection errors.
LANDSCAPE_MODE_RESTRICTED Work in landscape orientation is prohibited.

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,
  manual: true
}
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. 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,
  manual: true
}
The "Retry" button is pressed. `face-liveness`

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

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

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

`face-capture` 
{
  action: "PROCESS_FINISHED", 
  data: {
    reason: "An error has occurred",
    status: 0
  },
  manual: false
}
Component is initialized and ready to work. `face-liveness`

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

Response

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

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
  };
  sessionId: string
  status: number // liveness status: 0 if the person's liveness is confirmed, 1 if not. 
  transactionId: string
  images: string[] // array with the final image in base64 
}

The face-capture response has the following structure:

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

Attributes

face-capture

Attribute Info Data type Default value Values
locale The 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
copyright Show Regula copyright footer. boolean false true, false
camera-id Ability to select a camera. string undefined camera id string value
change-camera Show the camera switch button. boolean true true, false
start-screen Whether to show the start screen with video instruction. 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 the face. boolean true true, false

face-liveness

Attribute Info Data type Default value Values
locale The 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
url Backend url. string https://faceapi.regulaforensics.com/ any url
copyright Show Regula copyright footer. boolean false true, false
camera-id Ability to select a camera. string undefined camera id string value
change-camera Show the camera switch button. boolean true true, false
start-screen Whether to show the start screen with video instruction. 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 the face. boolean true true, false

Customization

Using CSS variables, you can change the font and the main colors of the components.

Variable Info Default value
--font-family Сomponent font. Noto Sans, sans-serif
--font-size Сomponent base font size. 16px
--main-color Button and frame color. #7E57C5
--hover-color Button hover color. #7c45b4
--active-color Button active color. #7E57C5
--plate-color Information plate color. #E8E8E8
--target-sector-color Target sector color (available only in face-liveness component). #BEABE2
--direction-sector-color Direction sector color (available only in face-liveness component). #EAEAEA

Example:

CSS:

.my-custom-style {
    --font-family: Arial, sans-serif;
    --main-color: green;
    --hover-color: red;
}

HTML:

<face-capture class="my-custom-style"></face-capture>

Examples

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

Additional resources

The Face web components are also available on Storybook.