Version: 1.14.0 (latest)

Web component

A web component is a user interface used to collect data about a user and their device, perform biometric checks, and send data to a server. It is integrated into the existing system on the front-end side and serves as an additional layer of user biometric verification.

How it works

The behavior of the web component is determined by its configuration settings and can change accordingly. The complete algorithm looks like this:

The web component is being initialized
The web component receives configuration from the front-end of the project, in which it is embedded and from the BAF server via its API. Once the configuration is received from the server, the configurations are combined into one.
If the same parameter is defined in both the client and server configurations, the value from the client configuration takes precedence.
After merging the configurations, the web component initializes the necessary services for operation, including the face detector, video recording modules, and other required components.
The web component determines if the user exists in the BAF system and checks their current status
The user is identified using a unique user ID, which can either be transmitted from an external system or defined directly within the web component via a form where the user enters their information. Once identified, the user’s status is checked in the BAF system. If the status is valid, the user is allowed to proceed; otherwise, the web component displays an error message indicating the invalid status and blocks further access.
If the unique user ID is provided through the configuration, the form will be skipped, and the status check will be performed immediately.
The web component gets access to the webcam of the user's device
The web component requests access to the user’s webcam. If a device is found and access is granted, it displays the video stream; otherwise, it shows an error message. If multiple devices are available, the user is given the option to select which one to use.
"Motion Control" biometric check
The web component generates a series of commands for the user to perform in front of the camera. These commands include: turning the head to the left, turning the head to the right, raising the head, moving closer to the camera, and moving away from the camera.
During this check, frames containing the user’s face are captured. These frames are then used for additional server-side checks, such as facial liveness detection, image quality assessment, and others.
Biometric verification of the user's face
This is an auxiliary stage that is activated when the "Motion Control" biometric check is enabled.
The web component captures the user’s head position and extracts frames containing the user’s face, which are then used for additional server-side checks, such as facial liveness, image quality, and others.
Validation of the collected data and the results of biometric checks
The web component generates a fingerprint of the user's device, sends all the collected data to the server and receives the user's path verification in response.

Installing web components

The component is supplied as a TGZ tdvc-face-onboarding archive. It also requires the tdvc library, which is supplied separately as an archive.

Move the archives to the root folder of your project 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 vary. An example of the final package file.json:
```
"dependencies": {
    "@tdvc/face-onboarding": "file:tdvc-face-onboarding-1.0.0.tgz"
}
```
Call the `npm install' command, which will install the library in your project.
For the web component to work correctly, you need to add a number of files to the directory where your project's static resources are stored, usually the public directory. After installing the package, move the networks folder from /node_modules/@tdvc/face-onboarding/ and frame_handler_worker.js from /node_modules/@tdvc/face-onboarding/dist to the public directory.

Importing and using a web component

Import the library and the styles for it.
Create the integration of the web components on the server.
Define the configuration of the web component.
Launch the project.

Example of initializing a component in TypeScript:

import tdvc from '@tdvc/face-onboarding';
import {
    TDVAthorizationOnboarding,
    TDVRegistrationOnboarding,
} from '@tdvc/face-onboarding/dist/class';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration';
import '@tdvc/face-onboarding/dist/css/style.css';

let lib: TDVRegistrationOnboarding | TDVAthorizationOnboarding;

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
};

function run() {
    if (window.location.pathname === '/registration') {
        lib = new tdvc.Register(config);
    } else {
        lib = new tdvc.Authorization(config);
    }
}

window.onload = async () => {
    run();
};

window.onbeforeunload = () => {
    lib?.destroy();
};

Interaction of a web component with an external system

Interactions between the web component and external systems are handled using callback functions (callbacks). The system determines its event-processing logic based on the data provided by these functions or on the fact that the callback was triggered. Several such functions are defined in the component’s configuration:

onMounted: (() => void) — a function that is called when the web component is fully initialized.
onError: ((message: string, code: string) => void) — a function that is called if an error occurred while traversing the user path.
onUpdate: (() => void) — a function that is called if, after an error occurs, the user wants to try again to traverse the user's path.
onIdentifyApplicantStatus: (applicant: {applicantId: string, status: number}) => void — a function that is called after receiving the applicant status from the server.
onBack: (() => void) — a function that is called if the user clicks on the "Back" button while selecting the camera, and thereby stops going through the user's path.
onMotion: ((type: 'left' | 'right' | 'up' | 'closer' | 'farther' | 'return', result: boolean | undefined) => void) — the function that is called during the biometric check "Motion Control". If the result value is undefined, then the verification has just begun, if true - successfully passed, if false - failed.
onGetReferenceImages: (referenceImages: string[]) => void; — a function that is called when the best face frames are collected. referenceImages are images in the base64 string format.
onStartValidation: (() => void) — the function that is called before the validation of the results begins.
onValidate: ((data: any) => void) — the function that is called after receiving the result of data validation from the server.

Localization

By default, the web component supports two localizations: Russian and English, and the default interface language is English. The localization of the component can be changed via configuration at the time of initialization of the web component. To do this, specify the language and locale fields in the config.

An example of changing the English localization to TypeScript:

import tdvc from '@tdvc/face-onboarding';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration'

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
    locales: {
        // If you want to leave the Russian localization by default
        ...tdvc.DefaultLocales.ru,
        // Editing the English localization
        en: {
            // We leave the others of this localization by default
            ...tdvc.DefaultLocales.en,
            Login: {
                // Leaving other locales of this block by default
                ...tdvc.DefaultLocales.en.Login,
                // Editing the desired message
                IsRequired: 'New locale message',
            },
        },
    },
};

To add a new localization, prepare a Java Script object that will contain all the same fields as the object with the English localization and define the text in the required language for each message identifier. The localization object that can be used as an example can be found in the README.md file in the delivery archive.

An example of adding a new localization to TypeScript:

import tdvc from '@tdvc/face-onboarding';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration'

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
    language: 'fr',
    locales: {
        // If you want to leave the Russian and English localization by default
        ...tdvc.DefaultLocales,
        // The key of the object must match the value in the language field
        fr: {
            Login: {
                IsRequired: 'Nouveau message de paramètres régionaux',
                ...
            },
            ...
        },
    },
};

Stylization

The styling of the web component is done through CSS. Interface elements contain identifiers and CSS classes through which you can customize their appearance.

The identifiers and CSS classes used for customization can be found in the @tdvc/face-onboarding/dist/css/style.css file.

Server version compatibility table and web components:

BAF	@tdvc/face-onboarding
1.14.*	1.14.*
1.13.*	1.13.*
1.12.*	1.12.*
1.10.*	1.10.-1.11.
1.9.*	1.9.*
1.8.*	1.8.*
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

How it works​

Installing web components​

Importing and using a web component​

Interaction of a web component with an external system​

Localization​

Stylization​

Server version compatibility table and web components:​