@regulaforensics/vp-frontend-face-components 2.0.0 → 3.0.0

package/README.md

@@ -1,28 +1,46 @@
-# Table of contents
-1. [About](#about)
-1. [Compatibility](#compatibility)
-1. [Install via NPM](#install-via-npm)
-1. [Install via CDN](#install-via-cdn)
-1. [Component settings](#component-settings)
-1. [Components events](#components-events)
-1. [Component response](#component-response)
-1. [Component attributes](#component-attributes)
-1. [Component customization](#component-customization)
-1. [Examples](#examples)
+# 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)
+- [Events](#events)
+- [Response](#response)
+- [Attributes](#attributes)
+- [Custom translations](#custom-translations)
+- [Examples](#examples)
+- [Additional resources](#additional-resources)
 
 ---
 
-## About
+## Overview
 
-This package contains web components for face recognition.
+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 <a href="https://docs.regulaforensics.com/develop/overview/#liveness-detection" target="_blank">liveness</a>.
+
+The available components are:
+
+- `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
+
+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](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)** |                                                66                                                 |                                                  62                                                  |                                                 -                                                 |
-| **Desktop**          |                                                66                                                 |                                                  63                                                  |                                                11                                                 |
+| **Mobile (Android)** |                                                69                                                 |                                                  63                                                  |                                                 -                                                 |
+| **Desktop**          |                                                66                                                 |                                                  69                                                  |                                                11                                                 |
 
 ## Install via NPM
 
@@ -39,26 +57,26 @@ npm init
 ```
 Answer the questions in the command line questionnaire.
 
-Install ```@regulaforensics/vp-frontend-face-components```:
+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.
+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 `@regulaforensics/vp-frontend-face-components` into your `index.js`:
 
 ```javascript
 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:
+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 create a face snapshot;
-1. ```<face-liveness></face-liveness>``` - for liveness verification.
+1. `<face-capture></face-capture>` - for creating a face snapshot;
+1. `<face-liveness></face-liveness>` - for performing liveness verification.
 
-Example:
+For example:
 
 ```html
 <!DOCTYPE html>
@@ -76,43 +94,158 @@ Example:
 
 ## Install via CDN
 
-Connect the script in your ```.html``` file. CDN link: ```unpkg.com/:package@:version/:file```
+Connect the script in your `.html` file. CDN link: `unpkg.com/:package@:version/:file`
 
-Example:
+For example:
 
 ```html
-<script src="https://unpkg.com/@regulaforensics/vp-frontend-face-components@1.2.0/dist/main.js"></script>
+<script src="https://unpkg.com/@regulaforensics/vp-frontend-face-components@latest/dist/main.js"></script>
 ```
 
 Add the name of the component to the html, as in the example above.
 
-## Component settings
-
-### face-liveness
+## Settings
 
-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
+You can set any parameter using `settings`. Find below examples of applying all the settings at once and just some of them.
 
-Example:
+Example of using all the settings:
 
-```javascript
+````javascript
 const component = document.getElementsByTagName('face-liveness')[0];
 
-component.sessionId = "ID"
-```
+component.settings = {
+    locale: 'en',
+    copyright: true,
+    cameraId: '123',
+    changeCamera: true,
+    startScreen: true,
+    closeDisabled: true,
+    finishScreen: true,
+    videoRecording: true,
+    url: 'https://your-server.com',
+    headers: {
+        Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+    },
+    tag: 'sessionIdValue',
+    retryCount: 5,
+    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,
+    }
+}
 
-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:
+Example of using just the selected settings:
+
+````javascript
+const yourSettings = {
+    locale: 'de',
+    videoRecording: false,
+    url: 'https://your-server.com',
+    headers: {
+        Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+    },
+    customization: {
+        fontFamily: 'Noto Sans, sans-serif',
+        successScreenImage: importedImage,
+    }
+}
 
-```javascript
 const component = document.getElementsByTagName('face-liveness')[0];
 
-component.headers = {
-    Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+component.settings = yourSettings;
+
+````
+
+Here are all the available settings:
+
+
+| Setting          | Info                                                                                                                                                                                                                                                                                                                                                                                                                                           | Data type |             Default value              |                                                                                             Values                                                                                             | Used in                          |
+|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:--------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|----------------------------------|
+| `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` | `face-liveness`, `face-capture`  |
+| `url`            | The 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`       | The ability to select a camera by defining the camera ID.                                                                                                                                                                                                                                                                                                                                                                                      | `string`  |              `undefined`               |                                                                                    `camera id string value`                                                                                    | `face-liveness`, `face-capture`  |
+| `changeCamera`   | Whether to show the camera switch button.                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean` |                 `true`                 |                                                                                        `true`, `false`                                                                                         | `face-liveness`, `face-capture`  |
+| `startScreen`    | Whether to show the start screen with video 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`, `face-capture`  |
+| `finishScreen`   | Whether to show the finish screen (`success screen`, `retry-screen`). If `true`, the finish screen is shown. If `false`, no finish screen will be displayed, and **the user will only have one attempt to pass the liveness check**.                                                                                                                                                                                                           | `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`  |
+| `videoRecording` | Whether to enable the video recording of the process. If set to `true`, the video is sent to the server. The video format depends on the browser: MP4 for Safari, WEB for other browsers.                                                                                                                                                                                                                                                      | `boolean` |                `false`                 |                                                                                        `true`, `false`                                                                                         | `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 element colors, fonts, and images using this object. See the customization section  below.                                                                                                                                                                                                                                                                                                                                   | `object`  |              `undefined`               |                                                                               object with customization settings                                                                               | `face-liveness`, `face-capture`  |
+
+## Customization
+
+You can customize colors of some elements, fonts, and images using the `customization` field in the `settings` object. The customization settings are the following:
+
+| Setting                                      | Info                                                                         | Migrate from            |            Data type            |      Default value      |
+|:---------------------------------------------|:-----------------------------------------------------------------------------|-------------------------|:-------------------------------:|:-----------------------:|
+| `fontFamily`                                 | The component font.                                                          | `--font-family`         |             string              | `Noto Sans, sans-serif` |
+| `fontSize`                                   | The component base font size.                                                | `--font-size`           |             string              |         `16px`          |
+| `onboardingScreenStartButtonBackground`      | The instruction screen button background color.                              | `--main-color`          |             string              |        `#7E57C5`        |
+| `onboardingScreenStartButtonBackgroundHover` | The instruction screen button background hover color.                        | `--hover-color`         |             string              |        `#7C45B4`        |
+| `onboardingScreenStartButtonTitle`           | The instruction screen button text color.                                    |                         |             string              |        `#FFFFFF`        |
+| `onboardingScreenStartButtonTitleHover`      | The instruction screen button text hover color.                              |                         |             string              |        `#FFFFFF`        |
+| `onboardingScreenIllumination`               | The instruction screen "Illumination" icon image.                            |                         | base64 or url or imported image |           ``            |
+| `onboardingScreenAccessories`                | The instruction screen "No accessories" icon image.                          |                         | base64 or url or imported image |           ``            |
+| `onboardingScreenCameraLevel`                | The instruction screen "Camera level" icon image.                            |                         | base64 or url or imported image |           ``            |
+| `cameraScreenFrontHintLabelBackground`       | The camera screen plate with info-message background color.                  | `--plate-color`         |             string              |        `#E8E8E8`        |
+| `cameraScreenFrontHintLabelText`             | The camera screen plate with info-message text color.                        |                         |             string              |        `#000000`        |
+| `cameraScreenSectorActive`                   | The user progress sector color (available only in  face-liveness component). |                         |             string              |        `#7E57C5`        |
+| `cameraScreenSectorTarget`                   | The target sector color (available only in face-liveness component).         | `--target-sector-color` |             string              |        `#BEABE2`        |
+| `cameraScreenStrokeNormal`                   | The stroke color of the camera circle.                                       |                         |             string              |        `#7E57C5`        |
+| `processingScreenProgress`                   | The processing screen spinner color.                                         |                         |             string              |        `#7E57C5`        |
+| `retryScreenEnvironmentImage`                | The Retry screen environment image.                                          |                         | base64 or url or imported image |           ``            |
+| `retryScreenPersonImage`                     | The Retry screen person image.                                               |                         | base64 or url or imported image |           ``            |
+| `retryScreenRetryButtonBackground`           | The Retry screen button background color.                                    | `--main-color`          |             string              |        `#7E57C5`        |
+| `retryScreenRetryButtonBackgroundHover`      | The Retry screen button background hover color.                              | `--hover-color`         |             string              |        `#7C45B4`        |
+| `retryScreenRetryButtonTitle`                | The Retry screen button text color.                                          |                         |             string              |        `#FFFFFF`        |
+| `retryScreenRetryButtonTitleHover`           | The Retry screen button text hover color.                                    |                         |             string              |        `#FFFFFF`        |
+| `successScreenImage`                         | The Success screen 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...',
+    }
 }
+
 ```
 
-## Components events
+
+## Events
 
 You can subscribe to the component events.
 
@@ -126,9 +259,9 @@ faceLivenessComponent.addEventListener('face-liveness', (event) => console.log(e
 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 `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:
+The generated event object (`event.detail`) contains three fields that describe the event:
 
 ```javascript
 {
@@ -140,16 +273,17 @@ The generated event object (```event.detail```) contains three fields that descr
 
 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``` |
+| 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:
+In cases of successful operation of the components, the `data` field will contain the following fields:
 
 ```javascript
 {
@@ -158,7 +292,7 @@ In cases of successful operation of the components, the ```data``` field will co
 }
 ```
 
-In cases of unsuccessful work, the ```data``` field will contain the following fields:
+In cases of unsuccessful work, the `data` field will contain the following fields:
 
 ```javascript
 {
@@ -167,19 +301,23 @@ In cases of unsuccessful work, the ```data``` field will contain the following f
 }
 ```
 
-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. |
+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.                                           |
+| `CONNECTION_ERROR`          |                                           Connection errors.                                            |
+| `LANDSCAPE_MODE_RESTRICTED` |                              Work in landscape orientation is prohibited.                               |
+| `TIMEOUT_ERROR`             |                                   Transaction failed due to timeout.                                    |
+| `CHANGE_CAMERA`             | The user has changed the camera. Return to start-screen or restart service if start-screen is disabled. |
+| `DEVICE_ROTATE`             | The user has rotated the device. Return to start-screen or restart service if start-screen is disabled. |
+| `APP_INACTIVE`              |                      The user has closed the tab or browser during the face capture process.                       |
+| `INCORRECT_CAMERA_ID`       |                                  No camera with the specified ID found.                                  |
 
 The table below describes the cases of event generation:
 
@@ -192,7 +330,7 @@ The table below describes the cases of event generation:
 <th>Event type</th>
 <th>
 
-Event object ```event.detail```
+Event object `event.detail`
 </th>
 <th>Description</th>
 </tr>
@@ -202,11 +340,10 @@ Event object ```event.detail```
 <td>The component is mounted in the DOM.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -214,8 +351,7 @@ For face-capture:
 ```javascript
 {
   action: "ELEMENT_VISIBLE", 
-  data: null,
-  manual: true
+  data: null
 }
 ```
 
@@ -224,7 +360,8 @@ For 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:
+For example:
+
 ```html
 <div id="add-event-listener-to-this-element">
   <face-liveness></face-liveness>
@@ -237,11 +374,10 @@ Example:
 <td>The "Get started" button is pressed.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -249,8 +385,7 @@ For face-capture:
 ```javascript
 {
   action: "PRESS_START_BUTTON", 
-  data: null,
-  manual: true
+  data: null
 }
 ```
 
@@ -261,11 +396,10 @@ For face-capture:
 <td>The "Retry" button is pressed.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -273,8 +407,7 @@ For face-capture:
 ```javascript
 {
   action: "PRESS_RETRY_BUTTON", 
-  data: null,
-  manual: true
+  data: null
 }
 ```
 
@@ -285,11 +418,10 @@ For face-capture:
 <td>The "Close" button is pressed.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -297,8 +429,7 @@ For face-capture:
 ```javascript
 {
   action: "CLOSE", 
-  data: null,
-  manual: true
+  data: null
 }
 ```
 
@@ -309,11 +440,10 @@ For face-capture:
 <td>The work of the component is completed successfully.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -325,7 +455,6 @@ For face-capture:
     response: { ... },
     status: 1
   },
-  manual: false
 }
 ```
 
@@ -336,11 +465,10 @@ For face-capture:
 <td>The work of the component failed.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
-
-For face-capture:  
-```face-capture```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -349,10 +477,9 @@ For face-capture:
 {
   action: "PROCESS_FINISHED", 
   data: {
-    reason: "An error has occurred",
+    reason: "An event has occurred",
     status: 0
   },
-  manual: false
 }
 ```
 
@@ -360,14 +487,38 @@ For face-capture:
 <td></td>
 </tr>
 <tr>
-<td>Component is initialized and ready to work.</td>
+<td>The work of the component finished by timeout.</td>
 <td>
 
-For face-liveness:  
-```face-liveness```
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
-For face-capture:  
-```face-capture```
+</td>
+<td>
+
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+    reason: "TIMEOUT_ERROR"
+    status: 0
+  },
+}
+```
+
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The component is initialized and ready to work.</td>
+<td>
+
+`face-liveness`
+<br>
+<br>
+`face-capture`
 
 </td>
 <td>
@@ -375,8 +526,7 @@ For face-capture:
 ```javascript
 {
   action: "SERVICE_INITIALIZED",
-  data: null,
-  manual: false
+  data: null
 }
 ```
 
@@ -386,11 +536,11 @@ For face-capture:
 </tbody>
 </table>
 
-## Component response
+## Response
 
-You can get the response of the component in the ```detail``` field of the event object.
+You can get the response of the component in the `detail` field of the event object.
 
-Example:
+For example:
 
 ```javascript
 const component = document.getElementsByTagName('face-capture')[0];
@@ -405,73 +555,130 @@ function listener(event) {
 component.addEventListener('face-capture', listener);
 ```
 
-Please find ```face-liveness``` response structure in [OpenAPI documentation](https://dev.regulaforensics.com/FaceSDK-web-openapi/#tag/liveness-2.0/operation/get_liveness_transaction).
+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
+  images: string[] // array with the final image in base64 
+}
+````
 
-The ```face-capture``` response has the following structure
+The `face-capture` response has the following structure:
 
 ```javascript
 {
   capture: string[] // array with the final image in base64 
 }
-````
+```
 
-## Component attributes
+## Attributes
+
+**Warning**. Passing parameters via attributes is deprecated. In future versions, support will be discontinued. Please use the settings.
 
 ### 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```                                                                                                                                                     |
+| 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**      | Whether to show the Regula copyright footer.                                                                                                                                                                                         |  boolean  |    `false`    |                                                                                        `true`, `false`                                                                                         |
+| **camera-id**      | Ability to select a camera.                                                                                                                                                                                                          |  string   |  `undefined`  |                                                                                    `camera id string value`                                                                                    |
+| **change-camera**  | Whether to show the camera switch button.                                                                                                                                                                                            |  boolean  |    `true`     |                                                                                        `true`, `false`                                                                                         |
+| **start-screen**   | 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 the face.            |  boolean  |    `true`     |                                                                                        `true`, `false`                                                                                         |
+| **finish-screen**  | Whether to show the finish screen (`success screen`, `retry-screen`). If `true`, the finish screen is shown. If `false`, no finish screen will be displayed, and **the user will only have one attempt to pass the liveness check**. |  boolean  |    `true`     |                                                                                        `true`, `false`                                                                                         |
+| **close-disabled** | 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
 
-| 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```                                                                                                                                                     |
-
-## Component 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:
-
-```css
-.my-custom-style {
-    --font-family: Arial, sans-serif;
-    --main-color: green;
-    --hover-color: red;
-}
+| 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**             | The backend URL.                                                                                                                                                                                                                     |  string   | `https://faceapi.regulaforensics.com/` |                                                                                            any url                                                                                             |
+| **copyright**       | Whether to show the Regula copyright footer.                                                                                                                                                                                         |  boolean  |                `false`                 |                                                                                        `true`, `false`                                                                                         |
+| **camera-id**       | The ability to select a camera by defining the camera ID.                                                                                                                                                                            |  string   |              `undefined`               |                                                                                    `camera id string value`                                                                                    |
+| **change-camera**   | Whether to 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`                                                                                         |
+| **finish-screen**   | Whether to show the finish screen (`success screen`, `retry-screen`). If `true`, the finish screen is shown. If `false`, no finish screen will be displayed, and **the user will only have one attempt to pass the liveness check**. |  boolean  |                 `true`                 |                                                                                        `true`, `false`                                                                                         |
+| **close-disabled**  | 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`                                                                                         |
+| **video-recording** | Whether to enable the video recording of the process. If set to `true`, the video is sent to the server. The video format depends on the browser: MP4 for Safari, WEB for other browsers.                                            |  boolean  |                `false`                 |                                                                                        `true`, `false`                                                                                         |
+
+
+## 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 [attributes](#component-attributes) section, the `locale` attribute):
+
+```javascript
+const element = document.querySelector('face-liveness');
+
+element.translations = {
+   en: { 
+     selfieTime: 'Get Selfie',
+   },
+};
 ```
 
-HTML:
+**Note**. To see the changes, don't forget to set the language you changed to the `locale` attribute:
 
 ```html
-<face-capture class="my-custom-style"></face-capture>
+<face-liveness locale="en"></face-liveness>
 ```
 
+The list of labels used in the component:
+
+| Label                         | Default message in `en` locale                                                                      |             Used in             |
+|:------------------------------|:----------------------------------------------------------------------------------------------------|:-------------------------------:|
+| **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` |
+| **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` |
+
 ## Examples
 
-You can see the examples of using the components on the [Samples page](https://github.com/regulaforensics/face-web-components-samples).
+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>.
+
+## Additional resources
+
+The Face SDK web components are also available on <a href="https://storybook-face.regulaforensics.com/" target="_blank">Storybook</a>.