@regulaforensics/vp-frontend-face-components 1.3.0 → 1.4.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
@@ -102,21 +102,280 @@ component.headers = {
 }
 ```
 
-## Component events
+## Components events
 
-You can subscribe to component events. In cases of successful and unsuccessful work, the following events will be triggered:
+You can subscribe to the component events.
 
-For the ```face-capture``` component - ```face-capture```  
-For the ```face-liveness``` component - ```face-liveness```  
+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
+}
+```
+
+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>
+
+```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
+}
+```
+
+</td>
+<td></td>
+</tr>
+<tr>
+<td>The "Retry" button is pressed.</td>
+<td>
 
-component.addEventListener('face-capture', () => alert('Event!'));
+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 +386,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);
     }
 }
@@ -140,31 +399,35 @@ component.addEventListener('face-capture', listener);
 
 ### 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                           |  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``` |
+| **copyright** | Show Regula copyright footer   |   ```false```   |                                                                                                                                                    ```true```, ```false```                                                                                                                                                     |
+| **camera-id** | Ability to select a camera     | ```undefined``` |                                                                                                                                                  ```camera id string value```                                                                                                                                                  |
 
 ### 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                           |               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                                                                                                                                                             |
+| **copyright** | Show Regula copyright footer   |                ```false```                 |                                                                                                                                                    ```true```, ```false```                                                                                                                                                     |
+| **camera-id** | Ability to select a camera     |              ```undefined```               |                                                                                                                                                  ```camera id string value```                                                                                                                                                  |
 
 ## 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.                                                                 |        ```#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)```   |
 
 Example:
 
@@ -186,4 +449,4 @@ HTML:
 
 ## Examples
 
-You can see examples of using the components [here](https://github.com/regulaforensics/face-web-components-samples).
+You can see examples of using the components [here](https://github.com/regulaforensics/face-web-components-samples).