@regulaforensics/vp-frontend-face-components 1.1.0 → 1.4.0

package/README.md

@@ -1,20 +1,29 @@
-# Table of сontents
+# Table of contents
 1. [About](#about)
-1. [Install via NPM](#npm)
-1. [Install via CDN](#cdn)
-1. [Component events](#events)
-1. [Component response](#response)
-1. [Component attributes](#attributes)
+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)
 
 ---
 
-<a name="about"></a>
 ## About
 
 This package contains web components for face recognition.
 
-<a name="npm"></a>
+## 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                                                 |
+
 ## Install via NPM
 
 On the command line, navigate to the root directory of your project:
@@ -65,7 +74,6 @@ Example:
 </html>
 ```
 
-<a name="cdn"></a>
 ## Install via CDN
 
 Connect the script in your ```.html``` file. CDN link: ```unpkg.com/:package@:version/:file```
@@ -73,28 +81,301 @@ Connect the script in your ```.html``` file. CDN link: ```unpkg.com/:package@:ve
 Example:
 
 ```html
-<script src="https://unpkg.com/@regulaforensics/vp-frontend-face-components@1.1.0/dist/main.js"></script>
+<script src="https://unpkg.com/@regulaforensics/vp-frontend-face-components@1.2.0/dist/main.js"></script>
 ```
 
 Add the name of the component to the html, as in the example above.
 
-<a name="events"></a>
-## Component events
+## Component settings
 
-You can subscribe to component events. In cases of successful and unsuccessful work, the following events will be triggered:
+### face-liveness
 
-For the ```face-capture``` component - ```face-capture```  
-For the ```face-liveness``` component - ```face-liveness```  
+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:
 
 ```javascript
-const component = document.getElementsByTagName('face-capture')[0];
+const component = document.getElementsByTagName('face-liveness')[0];
+
+component.headers = {
+    Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+}
+```
+
+## 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
+}
+```
+
+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.
 
-component.addEventListener('face-capture', () => alert('Event!'));
+Example:
+```html
+<div id="add-event-listener-to-this-element">
+  <face-liveness></face-liveness>
+</div>
 ```
 
-<a name="response"></a>
+</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
+{
+  action: "PRESS_START_BUTTON", 
+  data: null,
+  manual: true
+}
+```
+
+</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.
@@ -105,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);
     }
 }
@@ -114,23 +395,58 @@ function listener(event) {
 component.addEventListener('face-capture', listener);
 ```
 
-<a name="attributes"></a>
 ## Component attributes
 
 ### face-capture
 
-| Attribute | Info | Default value | Values |
-|:----------|:-----|:-------------:|:------:|
-| **locale** | the language of the component | ```en``` | ```en```, ```ru``` |
+| 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``` | ```en```, ```ru``` |
-| **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**  | С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:
+
+CSS:
+
+```css
+.my-custom-style {
+    --font-family: Arial, sans-serif;
+    --main-color: green;
+    --hover-color: red;
+}
+```
+
+HTML:
+
+```html
+<face-capture class="my-custom-style"></face-capture>
+```
 
-<a name="examples"></a>
 ## 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).