@regulaforensics/vp-frontend-face-components 8.3.2240-nightly → 8.3.2242-nightly
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -17
- package/dist/main.iife.js +5 -5
- package/dist/main.js +7 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
- [Settings](#settings)
|
|
9
9
|
- [Customization](#customization)
|
|
10
10
|
- [Package Resources](#package-resources)
|
|
11
|
+
- [Security](#security)
|
|
11
12
|
- [Events](#events)
|
|
12
13
|
- [Response](#response)
|
|
13
14
|
- [Custom Translations](#custom-translations)
|
|
@@ -15,8 +16,6 @@
|
|
|
15
16
|
- [Licensing](#licensing)
|
|
16
17
|
- [Additional Resources](#additional-resources)
|
|
17
18
|
|
|
18
|
-
---
|
|
19
|
-
|
|
20
19
|
## Overview
|
|
21
20
|
|
|
22
21
|
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>.
|
|
@@ -35,11 +34,12 @@ Important notes:
|
|
|
35
34
|
- The Face SDK Web Components and their methods strictly require secure contexts, so using the **HTTPS** protocol is a must.
|
|
36
35
|
- The considered components are registered on the **web page itself**, so make sure to import the library to your website before adding any of the components to the web page code.
|
|
37
36
|
- Only the modern browser versions are supported, see [compatibility](#compatibility). **Polyfills** are not included in the package by default.
|
|
37
|
+
- If your website uses Content Security Policy (CSP), make sure that WebAssembly execution is allowed. For details, see [Security](#security).
|
|
38
38
|
|
|
39
39
|
## Compatibility
|
|
40
40
|
|
|
41
41
|
| Devices |  |  |  |
|
|
42
|
-
|
|
42
|
+
|:---------------------|:-------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|
|
|
43
43
|
| **Mobile (iOS)** | 99 (iOS14.4+) | 99 (iOS14.4+) | 11 |
|
|
44
44
|
| **Mobile (Android)** | 69 | 63 | - |
|
|
45
45
|
| **Desktop** | 66 | 69 | 11 |
|
|
@@ -60,7 +60,6 @@ Run the following command:
|
|
|
60
60
|
```
|
|
61
61
|
npm init
|
|
62
62
|
```
|
|
63
|
-
|
|
64
63
|
Answer the questions in the command line questionnaire.
|
|
65
64
|
|
|
66
65
|
Install `@regulaforensics/vp-frontend-face-components`:
|
|
@@ -174,7 +173,7 @@ An example of using just the selected settings:
|
|
|
174
173
|
```javascript
|
|
175
174
|
const yourSettings = {
|
|
176
175
|
locale: 'de',
|
|
177
|
-
|
|
176
|
+
recordingProcess: 2,
|
|
178
177
|
url: 'https://your-server.com',
|
|
179
178
|
headers: {
|
|
180
179
|
Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==',
|
|
@@ -188,12 +187,13 @@ const yourSettings = {
|
|
|
188
187
|
const component = document.getElementsByTagName('face-liveness')[0];
|
|
189
188
|
|
|
190
189
|
component.settings = yourSettings;
|
|
190
|
+
|
|
191
191
|
```
|
|
192
192
|
|
|
193
193
|
Here are all the available settings:
|
|
194
194
|
|
|
195
195
|
| Setting | Info | Data type | Default value | Values | Used in |
|
|
196
|
-
|
|
196
|
+
|:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:--------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|---------------------------------|
|
|
197
197
|
| `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`, `uz` | `face-liveness`, `face-capture` |
|
|
198
198
|
| `url` | Backend URL. | `string` | `https://faceapi.regulaforensics.com/` | any url | `face-liveness` |
|
|
199
199
|
| `copyright` | Whether to show the Regula copyright footer. | `boolean` | `true` | `true`, `false` | `face-liveness`, `face-capture` |
|
|
@@ -206,23 +206,23 @@ Here are all the available settings:
|
|
|
206
206
|
| `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` |
|
|
207
207
|
| `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` | `undefined` | number of the attempts count | `face-liveness` |
|
|
208
208
|
| `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` |
|
|
209
|
-
| `customization` | You can customize the element's color, font, and image by using this object. See the [Customization](#customization) section below.
|
|
210
|
-
| `nonce` |
|
|
209
|
+
| `customization` | You can customize the element's color, font, and image by using this object. See the [Customization](#customization) section below. | `object` | `undefined` | object with customization settings | `face-liveness`, `face-capture` |
|
|
210
|
+
| `nonce` | A unique nonce value used to maintain a strict Content Security Policy. The value must match the nonce specified in your CSP header. See [Security](#security). | `string` | `undefined` | unique nonce value | `face-liveness`, `face-capture` |
|
|
211
211
|
| `rotationAngle` | Desktop only. By using the `rotationAngle` setter, you can specify an angle to compensate for the rotation of your physical camera. When set to values of `90` and `-90`, the component's design will switch to a mobile (vertical) orientation. | `number` | `undefined` | `0`,`180`,`90`,`-90` | `face-liveness`, `face-capture` |
|
|
212
212
|
| `holdStillDuration` | For the Capture screen, sets the duration that the user needs to stand straight and look in the camera. | `number` | `undefined` | seconds | `face-capture` |
|
|
213
213
|
| `timeoutInterval` | Timeout for the Capture screen. | `number` | `undefined` | seconds | `face-capture` |
|
|
214
|
-
| `livenessType` | You can choose a scenario for the
|
|
214
|
+
| `livenessType` | You can choose a scenario for the Liveness assessment. `0` - active liveness, full process that requires head rotation; `1` - passive liveness, a person is asked to only take a selfie, no head rotation required; `3` - passive liveness with blink, a person is asked to take a selfie and blink, no head rotation required. | `number` | `0` | `0`, `1`, `3` | `face-liveness` |
|
|
215
215
|
| `detectOcclusion` | Whether to disable face occlusion hint. | `boolean` | `true` | `true`, `false` | `face-capture` |
|
|
216
216
|
| `tenant` | A label used to group transactions by specific customers, applications, or other criteria. | `string` | `undefined` | tenant | `face-liveness` |
|
|
217
217
|
| `env` | A label used to differentiate transactions by development stages. | `string` | `undefined` | env | `face-liveness` |
|
|
218
|
-
| `captureButton` | Whether to enable user-triggered capture. Shows the **Capture** button, desktop layout height increases accordingly. When enabled, the shot is taken only on user action.
|
|
218
|
+
| `captureButton` | Whether to enable user-triggered capture. Shows the **Capture** button, desktop layout height increases accordingly. When enabled, the shot is taken only on user action. When `livenessType` is set to `3` (passive liveness with blink), `captureButton` is not supported. | `boolean` | `false` | `true`, `false` | `face-liveness`, `face-capture` |
|
|
219
219
|
|
|
220
220
|
## Customization
|
|
221
221
|
|
|
222
222
|
You can customize the color of some elements, fonts, and images with the help of the `customization` field in the `settings` object. The customization settings are the following:
|
|
223
223
|
|
|
224
224
|
| Setting | Info | Migrate from | Data type | Default value |
|
|
225
|
-
|
|
225
|
+
|:---------------------------------------------|:------------------------------------------------------------------------|-------------------------|:-------------------------------:|:-----------------------:|
|
|
226
226
|
| `fontFamily` | Font. | `--font-family` | string | `Noto Sans, sans-serif` |
|
|
227
227
|
| `fontSize` | Base font size. | `--font-size` | string | `16px` |
|
|
228
228
|
| `onboardingScreenStartButtonBackground` | Instruction screen button background color. | `--main-color` | string | `#7E57C5` |
|
|
@@ -402,7 +402,7 @@ const workerPath = component.settings.workerPath;
|
|
|
402
402
|
**2.** Upload all files (`Liveness.worker.js`, `Liveness.wasm`, `Liveness.data`) to your own location.
|
|
403
403
|
|
|
404
404
|
!!! warning
|
|
405
|
-
The files must be located in the same directory and have the same names as called before.
|
|
405
|
+
The files must be located in the same directory and have the same names as called before.
|
|
406
406
|
|
|
407
407
|
**3.** Update the `workerPath` setting to your custom host directory where all three files are located:
|
|
408
408
|
|
|
@@ -413,6 +413,72 @@ component.settings.workerPath = 'https://<CUSTOM_PATH_TO_WASM_AND_WORKER_FILES_P
|
|
|
413
413
|
|
|
414
414
|
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>.
|
|
415
415
|
|
|
416
|
+
## Security
|
|
417
|
+
|
|
418
|
+
This section describes security-related requirements and recommendations for using Face SDK Web Components.
|
|
419
|
+
|
|
420
|
+
### Secure Context
|
|
421
|
+
|
|
422
|
+
Face SDK Web Components require a secure browser context. Use **HTTPS** when running the components in production.
|
|
423
|
+
|
|
424
|
+
The components need access to the user's camera, so the browser will request camera permission before starting the capture or liveness process.
|
|
425
|
+
|
|
426
|
+
### Content Security Policy
|
|
427
|
+
|
|
428
|
+
Face SDK Web Components use WebAssembly to run the Face SDK core functionality in the browser. The WebAssembly module contains Regula's C++ code compiled for browser execution and wrapped with a JavaScript layer.
|
|
429
|
+
|
|
430
|
+
Some face detection and liveness operations are executed by the WebAssembly module through a worker process. Because of this, strict Content Security Policy configurations must explicitly allow WebAssembly execution.
|
|
431
|
+
|
|
432
|
+
If your website uses CSP, include one of the following source expressions in the `script-src` directive:
|
|
433
|
+
|
|
434
|
+
```http
|
|
435
|
+
Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval';
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
If `wasm-unsafe-eval` is not supported by your target browsers, use `unsafe-eval` instead:
|
|
439
|
+
|
|
440
|
+
```http
|
|
441
|
+
Content-Security-Policy: script-src 'self' 'unsafe-eval';
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
This requirement is expected and is related to WebAssembly execution in the browser. It does not mean that the component runs untrusted code or evaluates arbitrary customer-provided scripts.
|
|
445
|
+
|
|
446
|
+
### CSP Nonce
|
|
447
|
+
|
|
448
|
+
To maintain a strict CSP configuration for scripts, you can use the `nonce` setting.
|
|
449
|
+
|
|
450
|
+
For example:
|
|
451
|
+
|
|
452
|
+
```javascript
|
|
453
|
+
const component = document.querySelector('face-liveness');
|
|
454
|
+
|
|
455
|
+
component.settings = {
|
|
456
|
+
nonce: '<YOUR_NONCE_VALUE>'
|
|
457
|
+
};
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
The nonce value must match the nonce specified in your CSP header.
|
|
461
|
+
|
|
462
|
+
For details about the `nonce` setting, see [Settings](#settings).
|
|
463
|
+
|
|
464
|
+
### Package Resources
|
|
465
|
+
|
|
466
|
+
Face SDK Web Components load package resources required for WebAssembly execution:
|
|
467
|
+
|
|
468
|
+
* `Liveness.worker.js`
|
|
469
|
+
* `Liveness.wasm`
|
|
470
|
+
* `Liveness.data`
|
|
471
|
+
|
|
472
|
+
By default, these files are downloaded from Regula servers. If your CSP restricts external resources, make sure that the source of these files is allowed by your policy.
|
|
473
|
+
|
|
474
|
+
Alternatively, you can host these files on your own domain and configure `workerPath`. For details, see [Package Resources](#package-resources).
|
|
475
|
+
|
|
476
|
+
### Backend Connection
|
|
477
|
+
|
|
478
|
+
The `face-liveness` component communicates with the Face SDK Web Service using the URL specified in the `url` setting.
|
|
479
|
+
|
|
480
|
+
For production deployments, use HTTPS and protect access to the Web Service according to your security requirements, for example by using authentication on a proxy server.
|
|
481
|
+
|
|
416
482
|
## Events
|
|
417
483
|
|
|
418
484
|
You can subscribe to the component events.
|
|
@@ -439,7 +505,7 @@ The generated event object (`event.detail`) contains three fields that describe
|
|
|
439
505
|
}
|
|
440
506
|
```
|
|
441
507
|
|
|
442
|
-
### Type of
|
|
508
|
+
### Type of action
|
|
443
509
|
|
|
444
510
|
| Type of action | Description of the action | The component |
|
|
445
511
|
| :----------------------- | :-------------------------------------------------------------------------------------- | :------------------------------ |
|
|
@@ -473,7 +539,7 @@ In cases of unsuccessful work, the `data` field will contain the following field
|
|
|
473
539
|
### Table of event causes
|
|
474
540
|
|
|
475
541
|
| Reason | Description of the reason |
|
|
476
|
-
|
|
542
|
+
|:----------------------------|:--------------------------------------------------------------------------------------------------------|
|
|
477
543
|
| `WASM_ERROR` | Error in WASM. |
|
|
478
544
|
| `UNKNOWN_ERROR` | Unknown error. |
|
|
479
545
|
| `NOT_SUPPORTED` | The browser is not supported. |
|
|
@@ -490,7 +556,7 @@ In cases of unsuccessful work, the `data` field will contain the following field
|
|
|
490
556
|
| `INCORRECT_CAMERA_ID` | No camera with the specified ID found. |
|
|
491
557
|
| `WEBSERVICE_NOT_COMPATIBLE` | The web service and component versions are incompatible. |
|
|
492
558
|
| `HTTP_NOT_SUPPORTED` | The web component does not work over the HTTP protocol, use HTTPS instead. |
|
|
493
|
-
| `CANCELLED` | The user has clicked the Close button.
|
|
559
|
+
| `CANCELLED` | The user has clicked the Close button. |
|
|
494
560
|
| `BAD_FACE_QUALITY` | The facial image quality is too low. |
|
|
495
561
|
|
|
496
562
|
### Cases of event generation
|
|
@@ -868,8 +934,8 @@ element.translations = {
|
|
|
868
934
|
|
|
869
935
|
The list of labels used in the component:
|
|
870
936
|
|
|
871
|
-
| Label | Default message in `en` locale |
|
|
872
|
-
|
|
937
|
+
| Label | Default message in `en` locale |
|
|
938
|
+
|:------------------------------|:----------------------------------------------------------------------------------------------------|
|
|
873
939
|
| **showOnlyOneFace** | Make sure there is only one face on the screen. | `face-liveness`, `face-capture` |
|
|
874
940
|
| **preparingCamera** | Preparing the camera... | `face-liveness`, `face-capture` |
|
|
875
941
|
| **allowAccessCamera** | Allow access to the camera | `face-liveness`, `face-capture` |
|