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

package/README.md

@@ -4,7 +4,7 @@
 1. [Install via NPM](#install-via-npm)
 1. [Install via CDN](#install-via-cdn)
 1. [Component settings](#component-settings)
-1. [Component events](#component-events)
+1. [Components events](#components-events)
 1. [Component response](#component-response)
 1. [Component attributes](#component-attributes)
 1. [Component customization](#component-customization)
@@ -20,8 +20,8 @@ This package contains web components for face recognition.
 
 | 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)**     |                                           87 (iOS14.4+)                                           |                                            30 (iOS14.4+)                                             |                                                11                                                 |
-| **Mobile (Android)** |                                                96                                                 |                                                  94                                                  |                                                 -                                                 |
+| **Mobile (iOS)**     |                                           99 (iOS14.4+)                                           |                                            99 (iOS14.4+)                                             |                                                11                                                 |
+| **Mobile (Android)** |                                                66                                                 |                                                  62                                                  |                                                 -                                                 |
 | **Desktop**          |                                                66                                                 |                                                  63                                                  |                                                11                                                 |
 
 ## Install via NPM
@@ -90,6 +90,16 @@ Add the name of the component to the html, as in the example above.
 
 ### face-liveness
 
+The server generates a unique identifier for each session before starting a verification process. Using ```sessionId``` setter you can set custom value. Make sure that the ```sessionId``` is unique for each session
+
+Example:
+
+```javascript
+const component = document.getElementsByTagName('face-liveness')[0];
+
+component.sessionId = "ID"
+```
+
 After passing two stages of verification, the component sends the received data for processing to the API. Using ```headers``` setter you can set HTTP POST method headers.
 
 Example:
@@ -102,21 +112,280 @@ component.headers = {
 }
 ```
 
-## Component events
+## Components 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 actions:
+
+| Type of action            |      Description of the action       |      In which component is present      |
+|:--------------------------|:------------------------------------:|:---------------------------------------:|
+| ```ELEMENT_VISIBLE```     |  Component is appended in the DOM.   | ```face-liveness```, ```face-capture``` |
+| ```PRESS_START_BUTTON```  | The "Get started" button is pressed. | ```face-liveness```, ```face-capture``` |
+| ```PRESS_RETRY_BUTTON```  |    The "Retry" button is pressed.    | ```face-liveness```, ```face-capture``` |
+| ```CLOSE```               |    The "Close" button is pressed.    | ```face-liveness```, ```face-capture``` |
+| ```PROCESS_FINISHED```    | The component has finished its work. | ```face-liveness```, ```face-capture``` |
+| ```SERVICE_INITIALIZED``` | The component has started its work.  | ```face-liveness```, ```face-capture``` |
+
+In cases of successful operation of the components, the ```data``` field will contain the following fields:
+
+```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
+}
+```
 
-You can subscribe to component events. In cases of successful and unsuccessful work, the following events will be triggered:
+Table of error causes:
+
+| Reason                          |          Description of the reason           |
+|:--------------------------------|:--------------------------------------------:|
+| ```WASM_ERROR```                |                Error in WASM.                |
+| ```WASM_LICENSE```              |        Missing or incorrect license.         |
+| ```UNKNOWN_ERROR```             |                Unknown error.                |
+| ```NOT_SUPPORTED```             |        The browser is not supported.         |
+| ```CAMERA_UNKNOWN_ERROR```      |            Unknown camera error.             |
+| ```CAMERA_PERMISSION_DENIED```  |     Access to the camera is prohibited.      |
+| ```NO_CAMERA```                 |             There is no camera.              |
+| ```CONNECTION_ERROR```          |              Connection errors.              |
+| ```LANDSCAPE_MODE_RESTRICTED``` | Work in landscape orientation is prohibited. |
+
+The table below describes the cases of event generation:
+
+### face-liveness & face-capture
+
+<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>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
 
-For the ```face-capture``` component - ```face-capture```  
-For the ```face-liveness``` component - ```face-liveness```  
+```javascript
+{
+  action: "ELEMENT_VISIBLE", 
+  data: null,
+  manual: true
+}
+```
+
+</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.
 
 Example:
+```html
+<div id="add-event-listener-to-this-element">
+  <face-liveness></face-liveness>
+</div>
+```
+
+</td>
+</tr>
+<tr>
+<td>The "Get started" button is pressed.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
 
 ```javascript
-const component = document.getElementsByTagName('face-capture')[0];
+{
+  action: "PRESS_START_BUTTON", 
+  data: null,
+  manual: true
+}
+```
 
-component.addEventListener('face-capture', () => alert('Event!'));
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The "Retry" button is pressed.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
+
+```javascript
+{
+  action: "PRESS_RETRY_BUTTON", 
+  data: null,
+  manual: true
+}
 ```
 
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The "Close" button is pressed.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
+
+```javascript
+{
+  action: "CLOSE", 
+  data: null,
+  manual: true
+}
+```
+
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The work of the component is completed successfully.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
+
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+    response: { ... },
+    status: 1
+  },
+  manual: false
+}
+```
+
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The work of the component failed.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
+
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+    reason: "An error has occurred",
+    status: 0
+  },
+  manual: false
+}
+```
+
+</td>
+<td></td>
+</tr>
+<tr>
+<td>Component is initialized and ready to work.</td>
+<td>
+
+For face-liveness:  
+```face-liveness```
+
+For face-capture:  
+```face-capture```
+
+</td>
+<td>
+
+```javascript
+{
+  action: "SERVICE_INITIALIZED",
+  data: null,
+  manual: false
+}
+```
+
+</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+
 ## Component response
 
 You can get the response of the component in the ```detail``` field of the event object.
@@ -127,8 +396,8 @@ Example:
 const component = document.getElementsByTagName('face-capture')[0];
 
 function listener(event) {
-    if (event.detail) {
-        const response = event.detail;
+    if (event.detail.action === 'PROCESS_FINISHED' && event.detail.data.status === 1) {
+        const response = event.detail.data.response;
         console.log(response);
     }
 }
@@ -136,35 +405,54 @@ 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-capture``` response has the following structure
+
+```javascript
+{
+  capture: string[] // array with the final image in base64 
+}
+````
+
 ## Component attributes
 
 ### face-capture
 
-| Attribute  | Info                          | Default value |                                                                                                                                                             Values                                                                                                                                                             |
-|:-----------|:------------------------------|:-------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
-| **locale** | the language of the component |   ```en```    | ```ru```, ```en```, ```de```, ```pl```, ```it```, ```hu```, ```ch```, ```sk```, ```uk```, ```fr```, ```es```, ```pt```, ```ar```, ```nl```, ```id```, ```vi```, ```ko```, ```ms```, ```ro```, ```gr```, ```tr```, ```jp```, ```cz```, ```th```, ```hi```, ```bn```, ```he```, ```fi```, ```sv```, ```da```, ```hr```, ```no``` |
+| Attribute              | Info                                                                                                                                                                                                                             | Data type |  Default value  |                                                                                                                                                             Values                                                                                                                                                             |
+|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:---------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+| **locale**             | The language of the component.                                                                                                                                                                                                   |  string   |    ```en```     | ```ru```, ```en```, ```de```, ```pl```, ```it```, ```hu```, ```zh```, ```sk```, ```uk```, ```fr```, ```es```, ```pt```, ```ar```, ```nl```, ```id```, ```vi```, ```ko```, ```ms```, ```ro```, ```el```, ```tr```, ```ja```, ```cs```, ```th```, ```hi```, ```bn```, ```he```, ```fi```, ```sv```, ```da```, ```hr```, ```no``` |
+| **copyright**          | Show Regula copyright footer.                                                                                                                                                                                                    |  boolean  |   ```false```   |                                                                                                                                                    ```true```, ```false```                                                                                                                                                     |
+| **camera-id**          | Ability to select a camera.                                                                                                                                                                                                      |  string   | ```undefined``` |                                                                                                                                                  ```camera id string value```                                                                                                                                                  |
+| **change-camera**      | Show the camera switch button.                                                                                                                                                                                                   |  boolean  |   ```true```    |                                                                                                                                                    ```true```, ```false```                                                                                                                                                     |
+| **start-screen**       | Whether to show the start screen with video instruction. If ```true```, the start screen is shown. If ```false```, no start screen is shown and instead the camera of the device is turned on automatically to capture the face. |  boolean  |   ```true```    |                                                                                                                                                    ```true```, ```false```                                                                                                                                                     |
 
 ### face-liveness
 
-| Attribute  | Info                          |               Default value                |                                                                                                                                                             Values                                                                                                                                                             |
-|:-----------|:------------------------------|:------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
-| **locale** | the language of the component |                  ```en```                  | ```ru```, ```en```, ```de```, ```pl```, ```it```, ```hu```, ```ch```, ```sk```, ```uk```, ```fr```, ```es```, ```pt```, ```ar```, ```nl```, ```id```, ```vi```, ```ko```, ```ms```, ```ro```, ```gr```, ```tr```, ```jp```, ```cz```, ```th```, ```hi```, ```bn```, ```he```, ```fi```, ```sv```, ```da```, ```hr```, ```no``` |
-| **url**    | backend url                   | ```https://faceapi.regulaforensics.com/``` |                                                                                                                                                            any url                                                                                                                                                             |
+| 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**  | component font                                                                         | ```Noto Sans, sans-serif``` |
-| **--font-size**    | component base font size                                                               |         ```16px```          |
-| **--main-color**   | button and frame color                                                                 |        ```#663399```        |
-| **--second-color** | instruction image background color                                                     |        ```#EBE1F6```        |
-| **--third-color**  | instruction image portrait background color (available only in face-capture component) |        ```#C5B9D2```        |
-| **--hover-color**  | button hover color                                                                     |        ```#7c45b4```        |
-| **--active-color** | button active color                                                                    |        ```#663399```        |
-| **--plate-color**  | information plate color                                                                |  ```rgba(0, 0, 0, 0.6)```   |
+| 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:
 
@@ -186,4 +474,4 @@ HTML:
 
 ## Examples
 
-You can see examples of using the components [here](https://github.com/regulaforensics/face-web-components-samples).
+You can see the examples of using the components on the [Samples page](https://github.com/regulaforensics/face-web-components-samples).