Работа с Web-компонентой
Web-компонента — это инструмент захвата изображений, с помощью которого пользователь может выполнять регистрацию и авторизацию через веб-интерфейс. Обратите внимание, что Web-компонента работает только в браузерах, основанных на Chromium.
Доступны две версии Web-компоненты. Одна предназначена для работы со сценариями распознавания лиц (поддерживает новую бета-версию подсистемы LRS). Вторая предназначена для совместной проверки изображений лиц и документов.
Таблица совместимости версий:
| 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 |
Установка Web-компоненты
Компонента поставляется в виде архива TGZ. Также для работы библиотеки tdvc-face-onboarding необходима библиотека tdvc, которая также поставляется в виде архива.
Переместите архивы в корневую папку вашего проекта и добавьте следующие строки в ваш package.json в разделе зависимостей:
"@tdvc/face-onboarding": "file:tdvc-face-onboarding-{version}.tgz"
Версия архива может отличаться. Пример итогового файла package.json:
После этого вызовите команду npm install, которая установит библиотеку в ваш проект.
Для работы Web-компоненты необходим скрипт opencv.js. После установки пакета переместите папку «networks» из /node_modules/@tdvc/face-onboarding/ в папку "public" вашего проекта.
Импорт и использование Web-компоненты
Импортируйте библиотеку, а также стили для нее. При желании стилизация может быть переписана пользователем. Пример импорта библиотеки и стилей:
Теперь инициализируйте Web-компоненту. Для этого заполните файл конфигурации, подробное описание которого можно посмотреть ниже:
Web-компонента предоставляет два модуля: регистрацию и авторизацию. Чтобы использовать Web-компоненту, создайте экземпляр нужного вам модуля TVDOnboarding.
serverConfig
baseUrl (string) — URL-адрес BAF. Если вы передатите в качестве значения "/", то все запросы будут отправляться на хост, на котором развернута Web-компонента (обязательное поле).
bafToken (string) — секретный ключ веб-API BAF (обязательное поле).
networksPath (string) — параметр, в котором указан путь загрузки моделей FaceMesh. Значение по умолчанию — «/networks/»..
lrsToken (string) — токен доступа к Liveness Reflection(обязательное поле).
lrsDecryptKey (string) — ключ дешифровки для Liveness Reflection (обязательное поле).
iceServers (TIceServer[]) — объект с настройками WebRTC (обязательное поле).
ip (string) — IP stun сервера (обязательное поле).
port (string) — порт stun сервера (обязательное поле).
transport ('udp' | 'tcp') — протокол stun сервера (обязательное поле).
blConfig
cameraSettings (TCameraConfig) — объект с настройками камеры (обязательное поле).
showCameraSelect (boolean) — флаг, разрешающий выбор камеры (обязательное поле).
cameraId (string) — идентификатор устройства из navigator.mediaDevices. Если этот параметр передается, то параметр showCameraSelect должен иметь значение false.
cameraResolution ('fhd' | 'hd' | 'sd') — параметр, указывающий «идеальное» разрешение видео. Ключам соответствуют следующие разрешения: ключ fhd - разрешение 1920x1080, ключ hd - разрешение 1280x720, ключ sd - разрешение 640x360. Этот параметр указывает не точное разрешение видеопотока, а разрешение, к которому будет стремиться браузер. Значение по умолчанию - fhd.
showCameraSelect (boolean) — флаг, разрешающий выбор камеры (обязательное поле).
motionControl (boolean) — объект с настройками контроля движения. Доступны следующие поля:
enabled (boolean) — флаг, включающий проверку контроля движения.
attemptsCount (number) — количество попыток, которые доступны пользователю для прохождения контроля движения.
autoSubmit (boolean) — флаг, включающий автоматическое отправление запроса на валидацию после прохождения liveness.
motionControlEnabled (boolean) — флаг включающий функцию проверки движений.
callbacks (object) — объект с функциями обратного вызова. Доступны следующие функции:
onValidate ((data: any) => void) — функция, которая будет вызываться после получения ответа проверки. Возвращаемое значение — это объект с информацией проверки.
onError ((message: string, code: string) => void) — функция, которая будет вызываться в случае ошибки. Значением ответа является объект с сообщением ошибки.
onBack (() => void) — функция, которая будет вызвана после нажатия кнопки "Назад".
onUpdate (() => void) — функция, которая будет вызвана после нажатия кнопки "Обновить".
onMounted (() => void) — функция обратного вызова, которая будет вызываться после инициализации компоненты. Эта функция не возвращает значение.
onMotion ((type: 'left' | 'right' | 'up' | 'closer' | 'farther' | 'center' | 'return', result: boolean | undefined) => void) — функция, которая будет вызываться до и после каждого шаблона управления движением. Если переменная "result" равна undefined, функция была вызвана в начале шаблона, в противном случае — в конце.
applicationFields (TApplicantConfiguration) — настройка полей аппликанта, которые должны отображаться при регистрации или авторизации. Значения этих полей будут отправлены в запрос на создание аппликанта. Primary поле определяет, по какому ключу будет выполняться поиск аппликанта в базе данных. Обратите внимание, что основное поле должно быть единственным и включенным. Принимаемое значение представляет собой объект со следующим содержимым:
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 аппликанта для регистрации или авторизации.
Обратите внимание, что в конфигурации должно быть указано только одно из двух полей: applicantId или applicationFields.
interfaceConfig
mountElement (string) — ID элемента на странице, куда интегрируется Web-компонента (обязательное поле).
faceSettings (TFaceSettings) — объект с настройками зоны распознавания. Эта настройка позволяет регулировать размер отображаемой окружности лица. Эта настройка также влияет на размер лица, при котором начинается запись видео. Размеры вложенных объектов отвечают за размер стандартного круга. Круг для паттерна «ближе» определяется параметром closePercent, а для паттерна «дальше» — параметром FartherPercent. Параметры ClosePercent и FartherPercent показывают, насколько круг будет больше или меньше стандартного. Параметр sizeAccuracy отвечает за допустимую разницу в размерах отображаемого круга лица и BBox (измеряется в пикселях). Пример объекта с настройками (значения, указанные в примере, являются значениями по умолчанию):
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) — флаг, включающий отображение метрик соединения WebRTC: FPS и сети.
language (string) — текущий язык (обязательное поле).
locales (TLocales) — пользовательские локали для изменения текстов. Для удобства использования рекомендуем написать один файл с локалями и использовать его во всех конфигурациях Web-компоненты. В качестве принимаемого значения необходим объект со следующим содержимым:
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',
},
},
}
};
Пример инициализации компоненты регистрации:
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
);
Методы Web-компоненты
Destroy
Этот метод полностью демонтирует Web-компоненту.
Пример использования:
