Web component
Web component is an image capture tool that allows the user to perform registration and authorization through a web interface. Please note that the Web component works only in Chromium-based browsers. There are two different versions of the Web component available. One is designed to work with facial recognition scenarios (supports the new beta version of the LRS subsystem). The second one is designed for joint verification of images of faces and documents.
Version compatibility table:
| BAF | @tdvc/face-onboarding |
| 1.0.0 | 1.0.0 |
| 1.1.0 | 1.0.0-1.1.2 |
| 1.2.0 | 1.2.0-1.3.0 |
| 1.3.0-1.3.1 | 1.3.1 |
| 1.3.0-1.4.0 | 1.4.0-1.4.1 |
| 1.5.0 | 1.5.0 |
| 1.5.0-1.6.0 | 1.6.0-1.6.1 |
Install Web Component
The component is supplied as a TGZ archive. Also, for the tdvc-face-onboarding library to work, the tdvc library is required, which is also supplied as an archive. Move the archives to your project's root folder and add the following lines to your package.json in the dependencies section:
"@tdvc/face-onboarding": "file:tdvc-face-onboarding-{version}.tgz"
The archive version may differ. Example of the final package.json file:
After this, call the npm install command, which will install the library into your project.
For the component to work, the opencv.js script is required. After installing the package, move the "networks" folder from /node_modules/@tdvc/face-onboarding/ to the "public" folder of your project.
Import and use Web component
Import the library and the styles. If needed, you can overwrite the styling. Example of importing a library and styles:
Now initialize the Web component. To do this, fill out the configuration file described below:
The component provides two modules: registration and authorization. To use the component, create an instance of the TDVOnboarding module you need.
serverConfig
baseUrl (string) – URL address of BAF. If you pass the value "/", then requests will be sent to the host on which the web component is deployed. Required.
bafToken (string) – BAF Web API Secret Key. Required.
networksPath (string) – a parameter indicating where FaceMesh models will be loaded from. The default value is '/networks/'.
lrsToken (string) – Liveness Reflection service token. Required.
lrsDecryptKey (string) – Liveness Reflection service decrypt key. Required.
iceServers (TIceServer[]) – object with WebRTC settings. Required:
- ip (string) - IP of stun server. Required.
- port (string) - port of stun server. Required.
- transport ('udp' | 'tcp') - protocol of stun server. Required.
blConfig
cameraSettings (TCameraConfig) – object with camera settings. Required.
showCameraSelect (boolean) – flag allowing camera selection. Required.
cameraId (string) – deviceId from navigator.mediaDevices. If this parameter is passed, then the other parameter showCameraSelect must be false.
cameraResolution ('fhd' | 'hd' | 'sd') – a parameter indicating the "ideal" video resolution. The keys are related to the following resolutions: "fhd" key – 1920x1080 resolution, "hd" key – 1280x720 resolution, and "sd" key – 640x360 resolution. This setting doesn't indicate the exact resolution of the video stream, but only indicates the resolution that the browser will aim for. The default value is "fhd".
autoSubmit (boolean) – flag enabling automatic sending of a validation request after passing liveness.
motionControl (boolean) – object with Motion Control settings. The following fields are available:
enabled (boolean) – flag enabling Motion Control.
attemptsCount (number) – number of attempts a user can take to complete Motion Control.
callbacks (object) – object with callback hooks. Available next hooks:
onValidate ((data: any) => void) – the function that will be called after validation response is received.
onError ((message: string, code: string) => void) – the function that will be called on error.
onBack (() => void) – the function that will be called after the back button is pressed.
onUpdate (() => void) – the function that will be called after the update button is pressed.
onMounted (() => void) – the callback-function which will be called on the component mounted. This function doesn't return a value.
onMotion ((type: 'left' | 'right' | 'up' | 'closer' | 'farther' | 'center' | 'return', result: boolean | undefined) => void) – a function that will be called before and after each Motion control pattern. If the result variable is undefined, then the function was called at the beginning of the pattern, otherwise in the end.
applicationFields (TApplicantConfiguration) – setting up applicant fields that should be displayed during registration or authorization. The values of these fields will be sent to the request to create an applicant. The primary field determines by which key the applicant will be searched in the database. Note that there must be only one primary field and it must be enabled. The accepted value is an object with the following content:
applicationFields: {
firstName: { enabled: false, primary: false },
lastName: { enabled: false, primary: false },
phone: { enabled: false, primary: false },
email: { enabled: true, primary: true },
referenceId: { enabled: false, primary: false },
};applicantId (string) – ID of applicant for registration or authorization.
Please note that the configuration must only have one of two fields: applicantId or applicationFields.
interfaceConfig
mountElement (string) – ID of an element on the page where the component will be integrated. Required.
faceSettings (TFaceSettings) – object with recognition zone settings. This setting allows you to adjust the size of the displayed facial circumference. This setting also affects the face size at which video recording starts. The nested object sizes are responsible for the size of the standard circle. The circle for the "closer" pattern is determined by the parameter closerPercent, and for the pattern "farther" the parameter is fartherPercent. The parameters closerPercent and fartherPercent show how much the circle will be larger or smaller than the standard one. The sizeAccuracy parameter is responsible for the acceptable difference in the size of the displayed face circle and the BBox (measured in pixels).
Example of an object with settings (the values indicated in the example are default):
```javascript
faceSettings: {
sizes: {
mobile: {
width: 1.2,
height: 0.6,
},
pc: {
hd: {
width: 0.6,
height: 0.9,
},
fhd: {
width: 0.3,
height: 0.45,
},
},
},
closerPercent: 115,
fartherPercent: 85,
sizeAccuracy: 40,
}
```
showMetrics (boolean) – flag enabling display of WebRTC connection metrics: FPS and network.
language (string) – current language. Required.
locales (TLocales) – custom locales for changing texts. For ease of use, we recommend writing one file with locales and using it in all configurations of the component. The accepted value is an object with the following content:
locales: {
en: {
pages: {
Login: {
Authorization: 'Authorization',
Registration: 'Registration',
LoginButton: 'Continue',
InvalidEmail: 'Invalid email format',
MaxLengthField: 'Maximum field length is 150 characters',
IsRequired: 'This field is required',
firstName: 'First name',
lastName: 'Last name',
phone: 'Phone',
email: 'Email',
referenceId: 'ReferenceId',
WrongPhone: 'Wrong phone number',
CheckApplicant: 'Applicant verification',
LoadScripts: 'Load scripts',
},
Register: {
Header: 'Registration',
RegisterDescription1: 'Registering as ',
RegisterDescription2: 'Please complete the registration',
RegisterButton: 'Register',
BackToLoginButton: 'Back',
DontMove: "Please don't move.",
EstimateVideo: 'Checking the image quality',
Update: 'Update',
Processing: 'Processing in progress',
LoadModels: 'Loading models',
LoadVideoForm: 'Connecting the camera',
},
Authorize: {
Header: 'Authorization',
AuthorizeDescription1: 'Authorizing as ',
AuthorizeDescription2: 'Please complete the authorization',
AuthorizeButton: 'Log in',
BackToLoginButton: 'Back',
DontMove: "Please don't move.",
EstimateVideo: 'Checking the image quality',
Update: 'Update',
Processing: 'Processing in progress',
LoadModels: 'Loading models',
LoadVideoForm: 'Connecting the camera',
},
Errors: {
FaceValidationError: 'The image did not pass verification. Error code: ',
AntispoofingValidationError: 'Liveness check failed. Error code: ',
LowImageQuality: 'Poor image quality. Error code: ',
LivenessReflectionError: 'Liveness Reflection check failed. Error code: ',
NoFacesFound: 'No face found in the image. Error code: ',
SomeError: 'An error occurred, please try again later. Error code: ',
FacesDontBelongApplicant: 'Face matching check failed. Error code: ',
IDontSeeYou: 'You are not visible',
MoveFaceOnCenter: 'Please position yourself so that your face is in the center of the circle on the screen',
LookAtCamera: 'Please, turn your face to the camera',
LittleFace: 'Move closer to the camera',
BigFace: 'Move further away from the camera',
SlowEnternet:
'Your internet connection is slow. Image quality assessment may take long',
InCorrectCamera:
'The selected camera is not available or does not meet the minimum requirements. Error code: ',
NoCamera: 'No cameras available. Error code: ',
NoPermission:
'Permission to access the camera is not obtained. For further work, allow access to the camera in your browser settings. Error code: ',
MoreFaces: 'Many faces in the frame. Error code: ',
SafariError: 'Unfortunately, your browser is temporarily not supported at the moment',
BackToLoginButton: 'Back',
ApplicantNotFound: 'Incorrect data entered',
ApplicantAlreadyExist: 'This user already exists',
Update: 'Update',
ServerError: 'The server is temporarily unavailable. Error code: ',
ServerConfigError: 'Error on the server. Error code: ',
LoadScriptError: 'Loading script error. Error code:',
TensorflowError: 'Error when running Tensorflow model',
ApplicantBlocked: 'The applicant is blocked',
MCCrossMatchError: 'Facial substitution detected. Error code: ',
LRCrossMatchError: 'Facial substitution detected. Error code: ',
BlackListError: 'The applicant is on the black list. Error code: ',
RiskError: 'During validation, the risk triggered. Error code: ',
120004: 'FPS too low. Please try again. Error code: ',
120005: 'Error on the server. Please try again. Error code: ',
120006: 'Error on the server. Please try again. Error code: ',
120007: 'Error on the server. Please try again. Error code: ',
120008: 'Error on the server. Please try again. Error code: ',
120009: 'Please check the quality of your internet connection and try again. Error code: ',
120052: 'Error on the server. Please try again. Error code: ',
120053: 'Error on the server. Please try again. Error code: ',
120054: 'Error on the server. Please try again. Error code: ',
120055: 'Error while sending a message via DataChannel. Error code: ',
120057: 'Error in obtaining Motion Control pattern. Error code: ',
120060: 'Error on the server. Please try again. Error code: ',
120061: 'Error on the server. Please try again. Error code: ',
},
Success: {
Register: 'Registration completed successfully',
Authorize: 'Authorization completed successfully',
},
Liveness: {
TurnLeft: 'Turn left',
TurnRight: 'Turn right',
TurnUp: 'Lift your chin up while continuing to look at the screen',
LookAtCenter: 'Look into the camera',
Closer: 'Move closer to the camera',
Farther: 'Move further away from the camera',
Normal: 'Return to the original position',
TryFalled: 'Attempt failed',
CalculateLiveness: 'Calculating Liveness Reflection',
},
},
}
};
Registration component initialization example:
import TDVOnboarding from '@tdvc/face-onboarding';
import {
TBLConfig,
TInterfaceConfig,
TServerConfig,
} from '@tdvc/face-onboarding/dist/types';
import '@tdvc/face-onboarding/dist/css/style.css';
const serverConfig: TServerConfig = {
baseUrl: 'http://127.0.0.1:5173',
bafToken: 'sk_00000000-0000-0000-0000-000000000000',
lrsToken: '00000000-0000-0000-0000-000000000000',
lrsDecryptKey: '_iR_mxSoU4CLK5ReMmfck3zeKPgIiUhNLOKZYyszuCU=',
iceServers: [
{
ip: '127.0.0.1',
port: '32461',
transport: 'tcp',
},
],
};
const interfaceConfig: TInterfaceConfig = {
language: 'en',
mountElement: 'registrationEl',
locales,
showMetrics: true,
faceSettings: {
sizes: {
mobile: {
width: 1.2,
height: 0.6,
},
pc: {
hd: {
width: 0.6,
height: 0.9,
},
fhd: {
width: 0.3,
height: 0.45,
},
},
},
closerPercent: 115,
fartherPercent: 85,
sizeAccuracy: 40,
}
};
const blConfig: TBLConfig = {
cameraSettings: {
showCameraSelect: false,
cameraId:
'491526d7975631a5876944c8ca5734af21d1b7af6039b571a99eb9ca9de864e7',
cameraResolution: 'hd',
},
applicationFields: {
firstName: { enabled: false, primary: false },
lastName: { enabled: false, primary: false },
phone: { enabled: false, primary: false },
email: { enabled: true, primary: true },
referenceId: { enabled: false, primary: false },
},
motionControl: {
enabled: true,
attemptsCount: 2,
},
autoSubmit: true,
callbacks: {
onValidate(data) {
console.log('onValidate callback', data);
},
onError(message, code) {
console.log('onError callback', message, code);
},
onBack() {
console.log('onBack callback');
},
onMotion(type,currentAttemptNumber, result) {
console.log('onMotion callback', type, currentAttemptNumber, result);
},
onUpdate() {
console.log('onUpdate callback');
},
onMounted() {
console.log('onMounted callback');
},
},
};
const lib = new TDVOnboarding.Register(
serverConfig,
interfaceConfig,
blConfig
);
Methods
Destroy
The method completely dismantles the Web component.
Example:
