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 | ![]() |
![]() |
![]() |
---|---|---|---|
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
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 a face snapshot;<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` |
|
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:
|
The "Get started" button is pressed. |
`face-liveness`
`face-capture` |
|
|
The "Retry" button is pressed. |
`face-liveness`
`face-capture` |
|
|
The "Close" button is pressed. |
`face-liveness`
`face-capture` |
|
|
The work of the component is completed successfully. |
`face-liveness`
`face-capture` |
|
|
The work of the component failed. |
`face-liveness`
`face-capture` |
|
|
Component is initialized and ready to work. |
`face-liveness`
`face-capture` |
|
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.