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 | @tdvc/document-onboarding |
| 1.0.0 | 1.0.0 | 1.0.0 |
| 1.1.0 | 1.0.0-1.1.2 | 1.0.0 |
| 1.2.0 | 1.2.0-1.3.0 | 1.0.0 |
| 1.3.0-1.3.1 | 1.3.1 | 1.0.0 |
| 1.3.0-1.4.0 | 1.4.0 | 1.0.0 |
Without documents
Further instructions for installing and configuring the Web component are suitable when using BAF without documents. In this case, you need to use tdvc-face-onboarding Web component.
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.
platformToken (string) – Platform service token. Required.
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
showCameraSelect (boolean) – flag allowing camera selection. Required.
autoSubmit (boolean) - flag enabling automatic sending of a validation request after passing liveness.
motionControlEnabled (boolean) - flag enabling additional check of motion control.
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 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.
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 150 characters',
IsRequired: 'This field is required',
firstName: 'First name',
lastName: 'Last name',
phone: 'Phone',
email: 'Email',
referenceId: 'ReferenceId',
WrongPhone: 'Incorrect phone number',
},
Register: {
Header: 'Registration',
RegisterDescription1: 'Registering as ',
RegisterDescription2: 'Please complete the registration',
RegisterButton: 'Submit',
BackToLoginButton: 'Back',
DontMove: "Please don't move. Establishing a connection",
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: 'Submit',
BackToLoginButton: 'Back',
DontMove: "Please don't move. Establishing a connection",
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: ',
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: "I can't see you",
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',
AbortConnection:
'A connection to the server could not be established. Check the quality of the Internet and the web camera you are using. Error code: ',
SlowEnternet:
'You have a slow internet connection. Image quality assessment may take longer',
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 was 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 unsupported 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: ',
},
Success: {
SuccessHeader: 'You have successfully passed verification',
},
Liveness: {
TurnLeft: 'Turn left',
TurnRight: 'Turn right',
TurnUp: 'Look up',
LookAtCenter: 'Look into the camera',
Closer: 'Get closer to the camera',
Farther: 'Move away from the camera',
Normal: 'Return to original position',
TryFalled: 'Attempt failed',
},
},
}
};
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',
platformToken: '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,
};
const blConfig: TBLConfig = {
showCameraSelect: true,
livenessActiveEnabled: true,
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 },
},
callbacks: {
onValidate(data) {
console.log('onValidate callback', data);
},
onError(message, code) {
console.log('onError callback', message, code);
},
},
};
const lib = new TDVOnboarding.Register(
serverConfig,
interfaceConfig,
blConfig
);
Methods
Destroy
The method completely dismantles the Web component.
Example:
With documents
Further instructions for installing and configuring the Web component are suitable when using BAF with documents. In this case, you need to use tdvc-document-onboarding Web component.
Install Web component
Web component is supplied as an npm package in the form of a .tgz archive. To install the Web component, place it in the root of your project next to the package.json file.
In package.json in the dependencies section add the line:
"@tdvc/document-onboarding": "tdvc-document-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.
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:
Description of the Web component configuration
el (string) – ID of the element on the page where the Web component is integrated (required field).
applicantId (string) – applicant ID (required field).
domainId (string) – ID of the domain that contains settings and styles for the Web component (required field).
domainApi (string) – URL address for getting access to API (required field).
publicKey (string) – public key for getting access to API (required field).
isAuth (boolean) – flag used to indicate that only user authorization is required.
faceOnly (boolean) – flag used to indicate that registration and authorization should be by face only.
chunkPublicPath (string) – path to the folder with chunks. Specify the path on the server if you need to move the folder to a different location. The default path is 'networks'.
networkUrl (string) – path to the folder with neural networks. Specify the path on the server if you need to move the folder to a different location. The default path is 'networks'.
useCDN (boolean) – flag is enabled if you need to load 'networks' from a CDN, and not from your domain.
preferApiConfig (boolean) – flag is enabled if you prefer to use the TDV library configuration sent from BAF API instead of the configuration used when initializing the shell.
hideDocumentTitle (boolean) – this option enables/disables the display of document titles.
processingImageFormat (string) – this option switches the image format used for image processing.
callbacks (object) – an object with callback functions. The following functions are available:
onChange – callback function that will be called after each step has passed. The return value is an object with a type and an image.
onCameraError – function called if the camera is unavailable. The response value is an object with an error code and a message.
onReset – callback function that will be called after all steps are reset. The return value is an object with steps.
onRetakeHook – a function that will be called before resetting the current step. The return value is the object with the current step.
onValidate – a function that will be called after receiving a verification response. The return value is an object with verification information.
onError – a function that will be called in case of an error. The response value is an object with an error code and a message.
onReloaded – a function that will be called after the component reload is completed. This function doesn't return a value.
onMounted – a function that will be called on the mounted component. This function doesn't return a value.
submit – callback function that will be called after all steps have been completed. The return value is an object with the following content:
Example of Web component initialization:
Methods
Restart
The method completely restarts the Web component with the configuration with which it was initialized.
Example:
Set applicant
The method restarts the component with the passed applicant and the configuration with which it was initialized.
Example:
Update config
The method restarts the component with the passed configuration.
Example:
