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.7.0 | 1.7.0 |
| 1.5.0-1.7.0 | 1.6.0-1.6.3 |
| 1.5.0 | 1.5.0 |
| 1.3.0-1.4.0 | 1.4.0-1.4.1 |
| 1.3.0-1.3.1 | 1.3.1 |
| 1.3.0-1.3.1 | 1.3.1 |
| 1.2.0 | 1.2.0-1.3.0 |
| 1.1.0 | 1.0.0-1.1.2 |
| 1.0.0 | 1.0.0 |
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:
- Create Web component on server.
- 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.
Each module accepts a configuration object as a parameter. Below is a configuration description:
Fields configurable via the configuration object
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.
integrationId (string) - BAF Web API Secret Key. Required.
cameraId (string) - deviceId from navigator.mediaDevices. Optional.
applicantId (string) - ID of applicant for registration or authorization. Optional.
Please note that either applicantId must be specified or one field from applicationFields must be enabled and be primary in the configuration.
mountElement (string) - Id of an element on the page where the component will be integrated. Required.
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',
LivenessDelay: 'Before recording starts',
},
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',
},
},
}
};
callbacks (object) - object with callback hooks. Available next hooks:
onValidate ((data: any) => void) - the function that will be called after validation response received.
onError ((message: string, code: string) => void) - the function that will be called on error.
onBack (() => void) - a function that will be called after the back button is pressed.
onUpdate (() => void) - a function that will be called after the update button is pressed.
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 at the end.
onMounted (() => void) - a callback-function which will be called on the component mounted. This function doesn't return a value.
Fields configurable via the server
videoRecorderToken (string) - LVideo Recorder service token. Required to access API.
videoRecorderDecryptionKey (string) - Video Recorder service decrypt key. Used to protect data.
networksPath (string) - a parameter indicating where FaceMesh models will be loaded from. The default value is '/networks/'.
iceServers (TIceServer[]) - object with WebRTC settings.
iceCandidateType: ('stun' | 'turn') - type of ICE.
ipAddress (string) - IP of stun server.
port (string) - port of stun server.
iceCandidateTransport ('udp' | 'tcp') - protocol of stun server.
livenessTransport ('HTTP' | 'WebRTC) - This setting allows you to select the type of communication between the client and the server (WebRTC or HTTP) when passing liveness checks.
fingerprintWaitTime (number) - This setting allows you to set the maximum waiting time for data collection to generate a fingerprint(Default is 2000 ms). Data that has not been received during this time will not be included in the fingerprint.
faceModelSettings (TFaceModelConfig) - object with face mesh settings.
modelEnabled (boolean) - flag including a face mesh. Please note that if you turn this option off, Motion Control will no longer be available. Also, Liveness Reflection video recording will start after a certain time. The default is true.
timeToStartRecord (number) - time in milliseconds after which Liveness Reflection recording will start if the face mesh is turned off.
cameraSettings (TCameraConfig) - object with camera settings.
showCameraSelect (boolean) - flag allowing camera selection.
cameraResolution ('fhd' | 'hd' | 'sd') - A parameter indicating the "ideal" video resolution. The "fhd" key means 1920x1080 resolution, the "hd" key means 1280x720 resolution, and the "sd" key means 640x360 resolution. This setting does not indicate the exact resolution of the video stream, but only indicates the resolution that the browser will aim for. The default value is "fhd".
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.
autoSubmit (boolean) - flag enabling automatic sending of a validation request after passing liveness.
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 },
};
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 size is responsible for the size of the standard circle. The circle for the "closer" pattern is determined by the parameter closerPercent, and for the "farther" pattern 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 the default values):
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.
Registration component initialization example:
import TDVOnboarding from '@tdvc/face-onboarding';
import '@tdvc/face-onboarding/dist/css/style.css';
const lib = new TDVOnboarding.Register(
{
integrationId: '03520f5d-cdc3-4dca-9125-ece78c1050a9',
baseUrl: '/',
language: 'en',
mountElement: 'registrationEl',
locales,
callbacks: {
onValidate(data) {
console.log('onValidate callback', data);
},
onError(message, code) {
onsole.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');
},
},
}
);
Methods
Destroy
The method completely dismantles the Web component.
Example:
