# @regulaforensics/vp-frontend-face-components

> Regula framework agnostic web components to work with webcamera

Latest version **8.3.2310** (published 2026-08-04) · MIT license · 4.1K weekly downloads

## Install

```sh
npm install @regulaforensics/vp-frontend-face-components
pnpm add @regulaforensics/vp-frontend-face-components
yarn add @regulaforensics/vp-frontend-face-components
bun add @regulaforensics/vp-frontend-face-components
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

## Facts

| | |
|---|---|
| Version | 8.3.2310 |
| Published | 2026-08-04 |
| First published | 2021-10-12 |
| Weekly downloads | 4.1K |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 1.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Regula Forensics, Inc. |
| Maintainers | regula, ikliashchou |

## Links

- npm: https://www.npmjs.com/package/@regulaforensics/vp-frontend-face-components
- Homepage: https://storybook-face.regulaforensics.com/
- npm.io page: https://npm.io/package/@regulaforensics/vp-frontend-face-components

## Dependencies (2)

- [zustand](https://npm.io/package/zustand.md) ^4.3.7
- [@regulaforensics/facesdk-webclient](https://npm.io/package/@regulaforensics/facesdk-webclient.md) ^8.3.767

## Recent versions

- 8.3.2310 (latest) — 2026-08-04
- 8.4.2413-rc (rc) — 2026-10-03
- 8.4.2412-nightly (nightly) — 2026-10-03
- 8.4.2411-rc — 2026-10-02
- 8.4.2410-nightly — 2026-10-02
- 8.4.2409-rc — 2026-10-01
- 8.4.2408-rc — 2026-10-01
- 8.4.2407-nightly — 2026-10-01
- 8.4.2406-rc — 2026-09-30
- 8.4.2405-nightly — 2026-09-30
- 8.4.2404-rc — 2026-09-30
- 8.4.2403-nightly — 2026-09-30
- 8.4.2402-rc — 2026-09-29
- 8.4.2401-nightly — 2026-09-29
- 8.4.2400-nightly — 2026-09-28
- … 1020 more at https://npm.io/package/@regulaforensics/vp-frontend-face-components/versions

## README

# Face SDK Web Components

- [Overview](#overview)
- [Before You Start](#before-you-start)
- [Compatibility](#compatibility)
- [Install via NPM](#install-via-npm)
- [Install via CDN](#install-via-cdn)
- [Settings](#settings)
- [Customization](#customization)
- [Package Resources](#package-resources)
- [Security](#security)
- [Events](#events)
- [Response](#response)
- [Custom Translations](#custom-translations)
- [Examples](#examples)
- [Licensing](#licensing)
- [Additional Resources](#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 <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#liveness-assessment" target="_blank">face liveness</a>.

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](#compatibility). **Polyfills** are not included in the package by default.
- If your website uses Content Security Policy (CSP), make sure that WebAssembly execution is allowed. For details, see [Security](#security).

## Compatibility

| Devices              | ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png) | ![FireFox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari_48x48.png) |
|:---------------------|:-------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|
| **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 <a href="https://www.npmjs.com/package/@webcomponents/webcomponentsjs" target="_blank">@webcomponents/webcomponentsjs</a> 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`:

```javascript
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;
1. `<face-liveness></face-liveness>` - for performing liveness verification.

For example:

```html
<!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:

```html
<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.

Note that `settings` must be applied **after** the component has been added to the page’s DOM (for example, after calling `container.append(faceCapturEl)`). If settings are applied before the component is added to the DOM, they may not take effect.

An example of using all the settings:

```javascript
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',
    tenant: 'ABCDEF',
    env: 'Production',
    retryCount: 5,
    recordingProcess: 1,
    captureButton: false,
    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',
        cameraScreenStrokeWidth: 3,
        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:

```javascript
const yourSettings = {
    locale: 'de',
    recordingProcess: 2,
    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. The value is determined based on the following priority:<br><br>1. `locale` component attribute takes the highest priority if explicitly set.<br>2. If `locale` is not set, the system checks the `html.lang` attribute.<br>3. If no `html.lang` attribute is available, the system attempts to determine the language from `window.navigator`.<br>4. If none of the above are available, the default value `en` is used.                                                                                                                                                                         | `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`, `uz`, `ku`, `tg`, `ky`, `hy` | `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` |                 `true`                 |                                                                                           `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**. <br><br>In cases where `finishScreen` is set to `false`, we recommend to monitor [Events](#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`  |              `undefined`               |                                                                                     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](#customization) section below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `object`  |              `undefined`               |                                                                                  object with customization settings                                                                                  | `face-liveness`, `face-capture` |
| `nonce`             | A unique nonce value used to maintain a strict Content Security Policy. The value must match the nonce specified in your CSP header. See [Security](#security).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `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; `3` - passive liveness with blink, a person is asked to take a selfie and blink, no head rotation required.                                                                                                                                                                                                                                                                       | `number`  |                  `0`                   |                                                                                               `0`, `1`, `3`                                                                                               | `face-liveness`                 |
| `detectOcclusion`   | Whether to disable face occlusion hint.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean` |                 `true`                 |                                                                                           `true`, `false`                                                                                            | `face-capture`                  |
| `tenant`            | A label used to group transactions by specific customers, applications, or other criteria.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `string`  |              `undefined`               |                                                                                                tenant                                                                                                | `face-liveness`                 |
| `env`               | A label used to differentiate transactions by development stages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `string`  |              `undefined`               |                                                                                                 env                                                                                                  | `face-liveness`                 |
| `captureButton`     | Whether to enable user-triggered capture. Shows the **Capture** button, desktop layout height increases accordingly. When enabled, the shot is taken only on user action. When `livenessType` is set to `3` (passive liveness with blink), `captureButton` is not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean` |                `false`                 |                                                                                           `true`, `false`                                                                                            | `face-liveness`, `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`        |
| `cameraScreenStrokeWidth`                    | Stroke width of the camera circle.                                      |                         |             number              |            3            |
| `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 |           ``            |
| `faceQualityScreenMainImage`                 | Face quality screen main image.                                         |                         | base64 or url or imported image |           ``            |
| `faceQualityScreenCleanCameraImage`          | Face quality screen "Clean camera lens" icon image.                     |                         | base64 or url or imported image |           ``            |
| `faceQualityScreenIlluminationImage`         | Face quality screen "Illumination" icon image.                          |                         | base64 or url or imported image |           ``            |
| `faceQualityScreenAccessoriesImage`          | Face quality screen "No accessories" icon image.                        |                         | base64 or url or imported image |           ``            |
| `faceQualityScreenChangeBackgroundImage`     | Face quality screen "Change background" icon image.                     |                         | base64 or url or imported image |           ``            |

For example:

```javascript
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...',
    },
};
```

### CSS Parts

To customize the appearance, use the `::part` attribute to define the desired CSS properties. Note that `::part` styles take precedence over styles set via settings.

For example:

```javascript
/** general component overlay */
face-liveness {
    background-color: #e6e6e6;
}

/** web component container */
face-liveness::part(wc-container) {
    box-shadow: none;
    border-radius: 0;
}

/** instruction screen */
face-liveness::part(onboarding-screen-title) {
    text-decoration: underline;
}
face-liveness::part(onboarding-screen-subtitle) {
    text-decoration: underline;
}
face-liveness::part(onboarding-screen-start-button) {
    background-color: #7c7c7c;
}
face-liveness::part(onboarding-screen-start-button):hover {
    background-color: #bd7dff;
}
face-liveness::part(onboarding-screen-start-button) {
    color: #000;
}
face-liveness::part(onboarding-screen-start-button):hover {
    color: #000;
}

/** instruction screen icons */
/** you can set any image from url */
face-liveness::part(onboarding-screen-illumination) {
    background: #000;
}
face-liveness::part(onboarding-screen-accessories) {
    background: #000;
}
face-liveness::part(onboarding-screen-camera-level) {
    background: #000;
}

/** camera mode svg's */
face-liveness::part(camera-screen-sector-target) {
    border-left-color: #000;
}
face-liveness::part(camera-screen-stroke-normal) {
    stroke: #000;
}
face-liveness::part(camera-screen-sector-active) {
    stroke: #000;
}

/** message plate */
face-liveness::part(camera-screen-front-hint-label) {
    background: #000;
    color: yellow;
}

/** spinner */
face-liveness::part(processing-screen-progress)::before {
    border-top-color: #000;
}
/** success image */
face-liveness::part(success-screen-image) {
    background: #000;
}

/** retry screen */
face-liveness::part(retry-screen-environment-text) {
    text-decoration: underline;
}
face-liveness::part(retry-screen-environment-image) {
    background: rgb(88, 82, 82);
}
face-liveness::part(retry-screen-person-text) {
    text-decoration: underline;
}
face-liveness::part(retry-screen-person-image) {
    background: rgb(88, 82, 82);
}
/** retry button */
face-liveness::part(retry-screen-retry-button) {
    background: rgb(88, 82, 82);
}
face-liveness::part(retry-screen-title-text) {
    color: rgb(88, 82, 82);
    text-decoration: underline;
}
face-liveness::part(retry-screen-subtitle-text) {
    color: rgb(88, 82, 82);
    text-decoration: underline;
}
/** face-capture: change active Capture button icon color */
face-capture::part(camera-screen-capture-button-icon) {
  color: blue;
}
/** face-liveness: change active Capture button icon color */
face-liveness::part(camera-screen-capture-button-icon) {
    color: blue;
}

```

For more details about `::part()` CSS pseudo-elements, see the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part" target="_blank">MDN Web Docs article</a>.

## Package Resources

For proper operation, Face SDK Web Components require several package files:

- WASM (`Liveness.wasm`, `Liveness.data`)
- worker (`Liveness.worker.js`)

By default, these files are downloaded from Regula servers, but you can set your own sources. To do this, perform the following steps:

**1.** Retrieve the current worker path from the component settings. This path points to where the files are currently being loaded from (on Regula servers):

```javascript
const component = document.querySelector('face-liveness');
const workerPath = component.settings.workerPath;
```

**2.** Upload all files (`Liveness.worker.js`, `Liveness.wasm`, `Liveness.data`) to your own location.

!!! warning
    The files must be located in the same directory and have the same names as called before.

**3.** Update the `workerPath` setting to your custom host directory where all three files are located:

```javascript
const component = document.querySelector('face-liveness');
component.settings.workerPath = 'https://<CUSTOM_PATH_TO_WASM_AND_WORKER_FILES_PATH>';
```

To decrease file size, on your server you can apply the desired <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding" target="_blank">compression method</a>.

## Security

This section describes security-related requirements and recommendations for using Face SDK Web Components.

### Secure Context

Face SDK Web Components require a secure browser context. Use **HTTPS** when running the components in production.

The components need access to the user's camera, so the browser will request camera permission before starting the capture or liveness process.

### Content Security Policy

Face SDK Web Components use WebAssembly to run the Face SDK core functionality in the browser. The WebAssembly module contains Regula's C++ code compiled for browser execution and wrapped with a JavaScript layer.

Some face detection and liveness operations are executed by the WebAssembly module through a worker process. Because of this, strict Content Security Policy configurations must explicitly allow WebAssembly execution.

If your website uses CSP, include one of the following source expressions in the `script-src` directive:

```http
Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval';
```

If `wasm-unsafe-eval` is not supported by your target browsers, use `unsafe-eval` instead:

```http
Content-Security-Policy: script-src 'self' 'unsafe-eval';
```

This requirement is expected and is related to WebAssembly execution in the browser. It does not mean that the component runs untrusted code or evaluates arbitrary customer-provided scripts.

### CSP Nonce

To maintain a strict CSP configuration for scripts, you can use the `nonce` setting.

For example:

```javascript
const component = document.querySelector('face-liveness');

component.settings = {
    nonce: '<YOUR_NONCE_VALUE>',
};
```

The nonce value must match the nonce specified in your CSP header.

For details about the `nonce` setting, see [Settings](#settings).

### Package Resources

Face SDK Web Components load package resources required for WebAssembly execution:

- `Liveness.worker.js`
- `Liveness.wasm`
- `Liveness.data`

By default, these files are downloaded from Regula servers. If your CSP restricts external resources, make sure that the source of these files is allowed by your policy.

Alternatively, you can host these files on your own domain and configure `workerPath`. For details, see [Package Resources](#package-resources).

### Backend Connection

The `face-liveness` component communicates with the Face SDK Web Service using the URL specified in the `url` setting.

For production deployments, use HTTPS and protect access to the Web Service according to your security requirements, for example by using authentication on a proxy server.

## Events

You can subscribe to the component events.

For example:

```javascript
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:

```javascript
{
  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 action

| 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` |
| `PROCESSING_REQUEST`     | The component is sending data to the backend.                                           | `face-liveness`                 |
| `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:

```javascript
{
  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:

```javascript
{
  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.                              |
| `CANCELLED`                 | The user has clicked the Close button.                              |
| `BAD_FACE_QUALITY`          | The facial image quality is too low.                                                                    |
| `BAD_FRAME_SIZE`          | The shorter side of the frame (width or height) is less than 720 pixels. |

### Cases of event generation

<table>
<thead>
<tr>
<th>Event condition</th>
<th>Event type</th>
<th>Event object `event.detail`</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>The component is mounted in the DOM.</td>
<td>
`face-liveness`<br><br>`face-capture`
</td>
<td>

```javascript
{
  action: "ELEMENT_VISIBLE",
  data: null
}
```

</td>
<td>
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:

```html
<div id="add-event-listener-to-this-element">
    <face-liveness></face-liveness>
</div>
```

</td>
</tr>

<tr>
<td>The "Get started" button was pressed.</td>
<td>
`face-liveness`<br><br>`face-capture`
</td>
<td>

```javascript
{
  action: "PRESS_START_BUTTON",
  data: null
}
```

</td>
<td></td>
</tr>

<tr>
<td>The "Retry" button was pressed.</td>
<td>
`face-liveness`<br><br>`face-capture`
</td>
<td>

```javascript
{
  action: "PRESS_RETRY_BUTTON",
  data: null
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The "Close" button was pressed.</td>
<td>
`face-capture`
</td>
<td>

```javascript
{
  action: "CLOSE",
  data: {
      reason: "CANCELLED",
      status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The liveness assessment session had not started, but the "Close" button was pressed.</td>
<td>
  `face-liveness`
</td>
<td>

```javascript
{
  action: "CLOSE",
  data: {
    reason: "CANCELLED",
    status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The liveness assessment session had started before the "Close" button was pressed.</td>
<td>
`face-liveness`
</td>
<td>

```javascript
{
  action: "CLOSE",
  data: {
      reason: "CANCELLED",
      transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      status: 0
        }
}
```

</td>
<td></td>
</tr>

<tr>
<td>The work of the component is completed successfully.</td>
<td>
`face-liveness`<br><br>`face-capture`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
      response: { ... },
      status: 1
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The work of the component failed.</td>
<td>
`face-capture`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
    reason: "An event has occurred",
    status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The liveness assessment session had not started, but the work of the component failed.</td>
<td>
`face-liveness`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
    reason: "An event has occurred",
    status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The liveness assessment session had started, and then the work of the component failed.</td>
<td>
`face-liveness`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
      reason: "An event has occurred",
      transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      status: 0
        }
}
```

</td>
<td></td>
</tr>
                
<tr>
<td>The work of the component finished by timeout.</td>
<td>
        `face-capture`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
      reason: "TIMEOUT_ERROR",
      status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The work of the component finished by timeout.</td>
<td>
        `face-liveness`
</td>
<td>

```javascript
{
  action: "PROCESS_FINISHED",
  data: {
    reason: "TIMEOUT_ERROR",
    transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    status: 0
        }
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The component is initialized and ready to work.</td>
<td>
`face-capture`
</td>
<td>

```javascript
{
  action: "SERVICE_INITIALIZED",
  data: null
}
```

</td>
<td></td>
</tr>
        
<tr>
<td>The component is initialized and ready to work.</td>
<td>
`face-liveness`
</td>
<td>

```javascript
{
  action: "SERVICE_INITIALIZED",
  transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  data: null
}
```

</td>
<td></td>
</tr>
        
</tbody>
</table>

## Response

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

For example:

```javascript
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:

```javascript
{
  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, 3 - passive with blink
  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](#settings) section, the `locale` setting):

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

```javascript
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.                                                     | `face-liveness`, `face-capture` |
| **preparingCamera**           | Preparing the camera...                                                                             | `face-liveness`, `face-capture` |
| **allowAccessCamera**         | Allow access to the camera                                                                          | `face-liveness`, `face-capture` |
| **somethingWentWrong**        | Something went wrong                                                                                | `face-liveness`, `face-capture` |
| **incorrectCameraId**         | No camera with the specified ID found.                                                              | `face-liveness`, `face-capture` |
| **checkCameraId**             | Check if the specified camera ID is correct.                                                        | `face-liveness`, `face-capture` |
| **preparingService**          | Preparing the service...                                                                            | `face-liveness`, `face-capture` |
| **allowAccessToCamera**       | Allow access to the camera and reload this page to continue.                                        | `face-liveness`, `face-capture` |
| **error**                     | Error!                                                                                              | `face-liveness`, `face-capture` |
| **versionNotSupported**       | Your browser version is not supported.                                                              | `face-liveness`, `face-capture` |
| **updateBrowser**             | Update your browser version                                                                         | `face-liveness`, `face-capture` |
| **licenseError**              | A license error has occurred                                                                        | `face-liveness`, `face-capture` |
| **licenseExpired**            | The license cannot be found or has expired                                                          | `face-liveness`, `face-capture` |
| **onlyPortraitOrientation**   | Portrait orientation only                                                                           | `face-liveness`, `face-capture` |
| **turnDeviceIntoPortrait**    | Please turn your device into portrait mode                                                          | `face-liveness`, `face-capture` |
| **tryAgain**                  | Try again                                                                                           | `face-liveness`, `face-capture` |
| **noCameraAvailable**         | No camera available                                                                                 | `face-liveness`, `face-capture` |
| **checkCameraConnection**     | Check the camera connection and try again.                                                          | `face-liveness`, `face-capture` |
| **lookStraight**              | Look straight                                                                                       | `face-liveness`, `face-capture` |
| **fitYourFace**               | Center your face                                                                                    | `face-liveness`, `face-capture` |
| **moveCloser**                | Move closer                                                                                         | `face-liveness`, `face-capture` |
| **moveAway**                  | Move away                                                                                           | `face-liveness`, `face-capture` |
| **holdSteady**                | Hold steady                                                                                         | `face-liveness`, `face-capture` |
| **takeAPhoto**                | Take a selfie                                                                                       | `face-capture`                  |
| **processing**                | Processing...                                                                                       | `face-liveness`, `face-capture` |
| **retryButtonText**           | Retry                                                                                               | `face-liveness`, `face-capture` |
| **followGuidelinesText**      | But please follow these guidelines:                                                                 | `face-liveness`, `face-capture` |
| **letsTryAgainTitle**         | Let’s try that again                                                                                | `face-liveness`, `face-capture` |
| **noCameraPermission**        | Camera unavailable!                                                                                 | `face-liveness`, `face-capture` |
| **goButton**                  | Go                                                                                                  | `face-liveness`, `face-capture` |
| **selfieTime**                | Selfie time!                                                                                        | `face-liveness`, `face-capture` |
| **ambientLighting**           | Ambient lighting is not too bright or too dark and there are no shadows or glare on your face       | `face-liveness`                 |
| **noMaskSunglassesHeaddress** | Neutral facial expression (no smiling, eyes open and mouth closed), no mask, sunglasses or headwear | `face-liveness`                 |
| **turnHead**                  | Turn your head a bit                                                                                | `face-liveness`                 |
| **centerFaceTurnHead**        | Center your face, turn your head                                                                    | `face-liveness`                 |
| **centerFace**                | Center your face                                                                                    | `face-capture`                  |
| **errorCode**                 | Error code:                                                                                         | `face-liveness`                 |
| **illumination**              | Good illumination.                                                                                  | `face-liveness`, `face-capture` |
| **cameraLevel**               | Camera at eye level.                                                                                | `face-liveness`, `face-capture` |
| **noAccessories**             | No accessories: glasses, mask, hat, etc.                                                            | `face-liveness`, `face-capture` |
| **getReady**                  | Get ready                                                                                           | `face-liveness`, `face-capture` |
| **removeOcclusion**           | Remove items covering your face                                                                     | `face-liveness`, `face-capture` |
| **tooMuchTurn**               | Avoid turning your head too much. A small turn is enough.                                           | `face-liveness`, `face-capture` |
| **turnHeadUp**                | Turn head up a bit to look straight                                                                 | `face-liveness`, `face-capture` |
| **turnHeadDown**              | Turn head down a bit to look straight                                                               | `face-liveness`, `face-capture` |
| **turnHeadLeft**              | Turn head left a bit to look straight                                                               | `face-liveness`, `face-capture` |
| **turnHeadRight**             | Turn head right a bit to look straight                                                              | `face-liveness`, `face-capture` |
| **makeFaceFullyVisible**      | Remove anything covering your face                                                                  | `face-liveness`, `face-capture` |
| **blinkYourEyes**      | Blink your eyes          | `face-liveness`|
| **notSufficientQuality**      | Not sufficient selfie quality          | `face-liveness` |
| **cleanCameraLens**      | Clean camera lens          | `face-liveness` |
| **addMoreLight**      | Add more light          | `face-liveness` |
| **wipeOutOcclusions**      | Remove occlusions from face          | `face-liveness` |
| **changeBackground**      | Change background          | `face-liveness`  |

## Examples

You can find examples of using the components on the <a href="https://github.com/regulaforensics/face-web-components-samples" target="_blank">Samples page</a>.

## Licensing

The Face SDK Web Components do not require licensing. A license is only needed for the <a href="https://docs.regulaforensics.com/develop/face-sdk/web-service/" target="_blank">Face SDK Web Service</a>.

## Additional Resources

The Face SDK Web Components are also available on <a href="https://storybook-face.regulaforensics.com/" target="_blank">Storybook</a>.

---
_Source: https://npm.io/package/@regulaforensics/vp-frontend-face-components · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._