@regulaforensics/vp-frontend-face-components 7.1.1682-nightly → 7.1.1683-rc

package/README.md

@@ -7,6 +7,7 @@
 - [Install via CDN](#install-via-cdn)
 - [Settings](#settings)
 - [Customization](#customization)
+- [Package Resources](#package-resources)
 - [Events](#events)
 - [Response](#response)
 - [Custom Translations](#custom-translations)
@@ -18,7 +19,7 @@
 
 ## Overview
 
-The Face SDK Web Components let you add automatic capture of a user's selfie and liveness check to your web site. The components capture a face from the device camera and can either simply detect a face on the captured photo or confirm the face <a href="https://docs.regulaforensics.com/develop/overview/#liveness-detection" target="_blank">liveness</a>.
+The Face SDK Web Components let you add automatic capture of a user's selfie and liveness check to your web site. The components capture a face from the device camera and can either simply detect a face on the captured photo or confirm the <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#liveness-assessment" target="_blank">face liveness</a>.
 
 The available components are the following:
 
@@ -114,6 +115,8 @@ Note that we have removed the `videoRecording` setting. Now you should use `reco
 
 You can set any parameter using `settings`. Find below examples of applying all the settings at once as well as using just some of them.
 
+Note that `settings` must be applied **after** the component has been added to the page’s DOM (for example, after calling `container.append(faceCapturEl)`). If settings are applied before the component is added to the DOM, they may not take effect.
+
 An example of using all the settings:
 
 ````javascript
@@ -189,9 +192,9 @@ Here are all the available settings:
 
 | Setting             | Info                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Data type |             Default value              |                                                                                             Values                                                                                             | Used in                         |
 |:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:--------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|---------------------------------|
-| `locale`            | 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` |
+| `locale`            | Language of the component. The value is determined based on the following priority:<br><br>1. `locale` component attribute takes the highest priority if explicitly set.<br>2. If `locale` is not set, the system checks the `html.lang` attribute.<br>3. If no `html.lang` attribute is available, the system attempts to determine the language from `window.navigator`.<br>4. If none of the above are available, the default value `en` is used.  | `string`  |                  `en`                  | `ru`, `en`, `de`, `pl`, `it`, `hu`, `zh`, `sk`, `uk`, `fr`, `es`, `pt`, `ar`, `nl`, `id`, `vi`, `ko`, `ms`, `ro`, `el`, `tr`, `ja`, `cs`, `th`, `hi`, `bn`, `he`, `fi`, `sv`, `da`, `hr`, `no` | `face-liveness`, `face-capture` |
 | `url`               | Backend URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `string`  | `https://faceapi.regulaforensics.com/` |                                                                                            any url                                                                                             | `face-liveness`                 |
-| `copyright`         | Whether to show the Regula copyright footer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `boolean` |                 `true`                 |                                                                                        `true`, `false`                                                                                         | `face-liveness`, `face-capture` |
+| `copyright`         | Whether to show the Regula copyright footer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `boolean` |                `true`                 |                                                                                        `true`, `false`                                                                                         | `face-liveness`, `face-capture` |
 | `cameraId`          | Ability to select a camera by defining the camera ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `string`  |              `undefined`               |                                                                                    `camera id string value`                                                                                    | `face-liveness`, `face-capture` |
 | `changeCamera`      | Whether to show the "Camera Switch" button. Note that if `livenessType = 0` (active liveness), the button will not be displayed on mobile devices regardless of the `changeCamera` setting.                                                                                                                                                                                                                                                                                                                                                                                                                                  | `boolean` |                 `true`                 |                                                                                        `true`, `false`                                                                                         | `face-liveness`, `face-capture` |
 | `startScreen`       | Whether to show the Start screen with video instructions. If `true`, the start screen is shown. If `false`, no start screen is shown and instead the camera of the device is turned on automatically to capture a face.                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean` |                 `true`                 |                                                                                        `true`, `false`                                                                                         | `face-liveness`, `face-capture` |
@@ -257,10 +260,12 @@ component.settings = {
 ```
 
 ### CSS Parts
-To customize the appearance, use the part attribute and define the desired CSS properties. (Note: The specificity of the ::part styles is greater than that of the styles set via settings). Examples:
 
-```css
+To customize the appearance, use the `::part` attribute to define the desired CSS properties. Note that `::part` styles take precedence over styles set via settings.
+
+For example:
 
+```javascript
 /** general component overlay */
 face-liveness {
     background-color: #e6e6e6;
@@ -357,7 +362,37 @@ face-liveness::part(retry-screen-subtitle-text) {
 }
 ```
 
-For more details about ::part() CSS pseudo-elements, see the article at [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
+For more details about `::part()` CSS pseudo-elements, see the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part" target="_blank">MDN Web Docs article</a>.
+
+## Package Resources
+
+For proper operation, Face SDK Web Components require several package files: 
+
+* WASM (`Liveness.wasm`, `Liveness.data`)
+* worker (`Liveness.worker.js`)
+
+By default, these files are downloaded from Regula servers, but you can set your own sources. To do this, perform the following steps:
+
+**1.** Retrieve the current worker path from the component settings. This path points to where the files are currently being loaded from (on Regula servers):
+
+```javascript
+const component = document.querySelector('face-liveness');
+const workerPath = component.settings.workerPath;
+```
+
+**2.** Upload all files (`Liveness.worker.js`, `Liveness.wasm`, `Liveness.data`) to your own location.
+
+!!! warning
+    The files must be located in the same directory and have the same names as called before.
+
+**3.** Update the `workerPath` setting to your custom host directory where all three files are located:
+
+```javascript
+const component = document.querySelector('face-liveness');
+component.settings.workerPath = 'https://<CUSTOM_PATH_TO_WASM_AND_WORKER_FILES_PATH>';
+```
+
+To decrease file size, on your server you can apply the desired <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding" target="_blank">compression method</a>.
 
 
 ## Events
@@ -386,7 +421,7 @@ The generated event object (`event.detail`) contains three fields that describe
 }
 ```
 
-Type of actions:
+### Type of actions
 
 | Type of action           |                                Description of the action                                |          The component          |
 |:-------------------------|:---------------------------------------------------------------------------------------|:-------------------------------|
@@ -416,7 +451,7 @@ In cases of unsuccessful work, the `data` field will contain the following field
 }
 ```
 
-Table of event causes:
+### Table of event causes
 
 | Reason                      | Description of the reason                                                                               |
 |:----------------------------|:--------------------------------------------------------------------------------------------------------|
@@ -436,21 +471,16 @@ Table of event causes:
 | `INCORRECT_CAMERA_ID`       | No camera with the specified ID found.                                                                  |
 | `WEBSERVICE_NOT_COMPATIBLE` | The web service and component versions are incompatible.                                                |
 | `HTTP_NOT_SUPPORTED`        | The web component does not work over the HTTP protocol, use HTTPS instead.                              |
-| `CANCELLED`                 | The user has clicked by close button                                                                    |
-
-The table below describes the cases of event generation:
+| `CANCELLED`                 | The user has clicked the Close button.                              |
 
-### face-liveness & face-capture
+### Cases of event generation
 
 <table>
 <thead>
 <tr>
-<th>Event condition </th>
+<th>Event condition</th>
 <th>Event type</th>
-<th>
-
-Event object `event.detail`
-</th>
+<th>Event object `event.detail`</th>
 <th>Description</th>
 </tr>
 </thead>
@@ -458,12 +488,7 @@ Event object `event.detail`
 <tr>
 <td>The component is mounted in the DOM.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
-`face-capture`
-
+`face-liveness`<br><br>`face-capture`
 </td>
 <td>
 
@@ -476,7 +501,6 @@ Event object `event.detail`
 
 </td>
 <td>
-
 To receive this event, you must wrap the component in another element (for example, a div) and add an addEventListener to it. When the component appears in the DOM, the event will pop up.
 
 For example:
@@ -489,15 +513,11 @@ For example:
 
 </td>
 </tr>
+
 <tr>
-<td>The "Get started" button is pressed.</td>
+<td>The "Get started" button was pressed.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
-`face-capture`
-
+`face-liveness`<br><br>`face-capture`
 </td>
 <td>
 
@@ -511,15 +531,11 @@ For example:
 </td>
 <td></td>
 </tr>
+
 <tr>
-<td>The "Retry" button is pressed.</td>
+<td>The "Retry" button was pressed.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
-`face-capture`
-
+`face-liveness`<br><br>`face-capture`
 </td>
 <td>
 
@@ -533,37 +549,75 @@ For example:
 </td>
 <td></td>
 </tr>
+        
 <tr>
-<td>The "Close" button is pressed.</td>
+<td>The "Close" button was pressed.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
 `face-capture`
-
 </td>
 <td>
 
 ```javascript
 {
   action: "CLOSE", 
-  data: null
+  data: {
+      reason: "CANCELLED",
+      status: 0
+        }
 }
 ```
 
 </td>
 <td></td>
 </tr>
+        
 <tr>
-<td>The work of the component is completed successfully.</td>
+<td>The liveness assessment session had not started, but the "Close" button was pressed.</td>
+<td>
+  `face-liveness`
+</td>
 <td>
 
+```javascript
+{
+  action: "CLOSE", 
+  data: {
+    reason: "CANCELLED",
+    status: 0
+        }
+}
+```
+
+</td>
+<td></td>
+</tr>
+        
+<tr>
+<td>The liveness assessment session had started before the "Close" button was pressed.</td>
+<td>
 `face-liveness`
-<br>
-<br>
-`face-capture`
+</td>
+<td>
+
+```javascript
+{
+  action: "CLOSE", 
+  data: {
+      reason: "CANCELLED",
+      transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+      status: 0
+        }
+}
+```
 
+</td>
+<td></td>
+</tr>
+
+<tr>
+<td>The work of the component is completed successfully.</td>
+<td>
+`face-liveness`<br><br>`face-capture`
 </td>
 <td>
 
@@ -571,24 +625,41 @@ For example:
 {
   action: "PROCESS_FINISHED", 
   data: {
-    response: { ... },
-    status: 1
-  },
+      response: { ... },
+      status: 1
+        }
 }
 ```
 
 </td>
 <td></td>
 </tr>
+        
 <tr>
 <td>The work of the component failed.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
 `face-capture`
+</td>
+<td>
+
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+    reason: "An event has occurred",
+    status: 0
+        }
+}
+```
 
+</td>
+<td></td>
+</tr>
+        
+<tr>
+<td>The liveness assessment session had not started, but the work of the component failed.</td>
+<td>
+`face-liveness`
 </td>
 <td>
 
@@ -598,22 +669,61 @@ For example:
   data: {
     reason: "An event has occurred",
     status: 0
-  },
+        }
+}
+```
+
+</td>
+<td></td>
+</tr>
+        
+<tr>
+<td>The liveness assessment session had started, and then the work of the component failed.</td>
+<td>
+`face-liveness`
+</td>
+<td>
+
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+      reason: "An event has occurred",
+      transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+      status: 0
+        }
 }
 ```
 
 </td>
 <td></td>
 </tr>
+                
 <tr>
 <td>The work of the component finished by timeout.</td>
+<td>
+        `face-capture`
+</td>
 <td>
 
-`face-liveness`
-<br>
-<br>
-`face-capture`
+```javascript
+{
+  action: "PROCESS_FINISHED", 
+  data: {
+      reason: "TIMEOUT_ERROR",
+      status: 0
+        }
+}
+```
 
+</td>
+<td></td>
+</tr>
+        
+<tr>
+<td>The work of the component finished by timeout.</td>
+<td>
+        `face-liveness`
 </td>
 <td>
 
@@ -621,30 +731,46 @@ For example:
 {
   action: "PROCESS_FINISHED", 
   data: {
-    reason: "TIMEOUT_ERROR"
+    reason: "TIMEOUT_ERROR",
+    transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     status: 0
-  },
+        }
 }
 ```
 
 </td>
 <td></td>
 </tr>
+        
 <tr>
 <td>The component is initialized and ready to work.</td>
 <td>
-
-`face-liveness`
-<br>
-<br>
 `face-capture`
+</td>
+<td>
+
+```javascript
+{
+  action: "SERVICE_INITIALIZED",
+  data: null
+}
+```
 
+</td>
+<td></td>
+</tr>
+        
+<tr>
+<td>The component is initialized and ready to work.</td>
+<td>
+`face-liveness`
 </td>
 <td>
 
 ```javascript
 {
   action: "SERVICE_INITIALIZED",
+  transactionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   data: null
 }
 ```
@@ -652,6 +778,7 @@ For example:
 </td>
 <td></td>
 </tr>
+        
 </tbody>
 </table>
 
@@ -769,7 +896,6 @@ The list of labels used in the component:
 | **turnHeadLeft**              | Turn head left a bit to look straight                                                               | `face-liveness`, `face-capture` |
 | **turnHeadRight**             | Turn head right a bit to look straight                                                              | `face-liveness`, `face-capture` |
 
-
 ## Examples
 
 You can find examples of using the components on the <a href="https://github.com/regulaforensics/face-web-components-samples" target="_blank">Samples page</a>.

package/dist/index.d.ts

@@ -180,7 +180,48 @@ export declare class FaceLivenessWebComponent extends HTMLElement {
     disconnectedCallback(): void;
 }
 
-export declare type FaceTranslations = Partial<Record<Labels, string>>;
+export declare interface FaceTranslations {
+    showOnlyOneFace?: string;
+    preparingCamera?: string;
+    allowAccessCamera?: string;
+    somethingWentWrong?: string;
+    incorrectCameraId?: string;
+    checkCameraId?: string;
+    preparingService?: string;
+    allowAccessToCamera?: string;
+    error?: string;
+    versionNotSupported?: string;
+    updateBrowser?: string;
+    licenseError?: string;
+    licenseExpired?: string;
+    onlyPortraitOrientation?: string;
+    turnDeviceIntoPortrait?: string;
+    tryAgain?: string;
+    noCameraAvailable?: string;
+    checkCameraConnection?: string;
+    noMaskSunglassesHeaddress?: string;
+    ambientLighting?: string;
+    lookStraight?: string;
+    fitYourFace?: string;
+    moveCloser?: string;
+    moveAway?: string;
+    holdSteady?: string;
+    turnHead?: string;
+    processing?: string;
+    retryButtonText?: string;
+    followGuidelinesText?: string;
+    letsTryAgainTitle?: string;
+    noCameraPermission?: string;
+    goButton?: string;
+    centerFaceTurnHead?: string;
+    centerFace?: string;
+    selfieTime?: string;
+    errorCode?: string;
+    illumination?: string;
+    cameraLevel?: string;
+    noAccessories?: string;
+    getReady?: string;
+}
 
 export declare class FullScreenContainer extends HTMLElement {
     private _root;
@@ -202,11 +243,7 @@ export declare interface IFaceLiveness extends IFaceDetection {
     'device-orientation'?: boolean;
 }
 
-declare type Labels = 'showOnlyOneFace' | 'preparingCamera' | 'allowAccessCamera' | 'somethingWentWrong' | 'incorrectCameraId' | 'checkCameraId' | 'preparingService' | 'allowAccessToCamera' | 'error' | 'versionNotSupported' | 'updateBrowser' | 'licenseError' | 'licenseExpired' | 'onlyPortraitOrientation' | 'turnDeviceIntoPortrait' | 'tryAgain' | 'noCameraAvailable' | 'checkCameraConnection' | 'noMaskSunglassesHeaddress' | 'ambientLighting' | 'lookStraight' | 'fitYourFace' | 'moveCloser' | 'moveAway' | 'holdSteady' | 'turnHead' | 'removeOcclusion' | 'turnHeadUp' | 'turnHeadDown' | 'turnHeadLeft' | 'turnHeadRight' | 'blinkYourEyes' | 'processing' | 'retryButtonText' | 'followGuidelinesText' | 'letsTryAgainTitle' | 'noCameraPermission' | 'goButton' | 'centerFaceTurnHead' | 'centerFace' | 'selfieTime' | 'errorCode' | 'illumination' | 'cameraLevel' | 'noAccessories' | 'getReady' | 'httpNotSupported' | 'webServerNotCompatible' | 'processCompleted';
-
-declare type Languages = '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';
-
-export declare type Locales = Languages | string;
+export declare type Locales = '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' | string;
 
 export declare const RecordingProcess: {
     readonly ASYNCHRONOUS_UPLOAD: 0;