Работа с Веб-компонентой
Веб-компонента — это инструмент захвата изображений, с помощью которого пользователь может выполнять регистрацию и авторизацию через веб-интерфейс. Обратите внимание, что веб-компонента работает только в браузерах, основанных на Chromium.
Доступны две версии веб-компоненты. Одна предназначена для работы со сценариями распознавания лиц (поддерживает новую бета-версию подсистемы LRS). Вторая предназначена для совместной проверки изображений лиц и документов.
Таблица совместимости версий:
| 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 |
Установка веб-компоненты
Компонента поставляется в виде архива TGZ. Также для работы библиотеки tdvc-face-onboarding необходима библиотека tdvc, которая также поставляется в виде архива.
Переместите архивы в корневую папку вашего проекта и добавьте следующие строки в ваш package.json в разделе зависимостей:
"@tdvc/face-onboarding": "file:tdvc-face-onboarding-{version}.tgz"
Версия архива может отличаться. Пример итогового файла package.json:
После этого вызовите команду npm install, которая установит библиотеку в ваш проект.
Для работы веб-компоненты необходим скрипт opencv.js. После установки пакета переместите папку «networks» из /node_modules/@tdvc/face-onboarding/ в папку "public" вашего проекта.
Импорт и использование веб-компоненты
Импортируйте библиотеку, а также стили для нее. При желании стилизация может быть переписана пользователем. Пример импорта библиотеки и стилей:
Теперь инициализируйте веб-компоненту.
- Создайте веб-компоненту на сервере.
- Для этого заполните файл конфигурации, подробное описание которого можно посмотреть ниже:
Веб-компонента предоставляет два модуля: регистрации и авторизации. Чтобы использовать веб-компоненту, создайте экземпляр нужного вам модуля TDVOnboarding.
Каждый модуль принимает в качестве параметров объект конфигурации. Ниже приведено описание конфигурации:
Поля, настраиваемые с помощью объекта конфигурации
baseUrl (string) - URL-адрес BAF. Если вы передадите значение «/», то запросы будут отправляться на хост, на котором развернут веб-компонент. Обязательное поле.
integrationId (string) - секретный ключ BAF Web API. Обязательное поле.
cameraId (string) - идентификатор устройства из navigator.mediaDevices. Опциональное поле.
applicantId (string) - идентификатор аппликанта для регистрацию или авторизации. Опциональное поле.
Обратите внимание, что в конфигурации должен быть указан либо applicantId, либо одно поле из applicationFields должно быть включено и быть основным.
mountElement (string) - идентификатор элемента на странице, в который будет интегрирована веб-компонента. Обязательное поле.
language (string) - язык интерфейса. Обязательное поле.
locales (TLocales) - пользовательские локали для изменения текстов. Для удобства использования мы рекомендуем записать один файл с локалями и использовать его во всех конфигурациях компонента. Принимаемое значение - объект со следующим содержимым:
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) - объект с функциями обратного вызова. Доступны следующие функции:
onValidate ((data: any) => void) - функция, которая будет вызвана после получения ответа на валидацию.
onError ((message: string, code: string) => void) - функция, которая будет вызвана при ошибке.
onBack (() => void) - функция, которая будет вызвана после нажатия кнопки «Назад».
onUpdate (() => void) - функция, которая будет вызвана после нажатия кнопки "Обновить".
onMotion ((type: 'left' | 'right' | 'up' | 'closer' | 'farther' | 'center' | 'return', result: boolean | undefined) => void) - функция, которая будет вызываться до и после каждого шаблона управления движением. Если переменная "result" равна undefined, функция была вызвана в начале шаблона, в противном случае — в конце.
onMounted (() => void) - функция, которая будет вызываться после инициализации компоненты. Эта функция не возвращает значение.
Поля, настраиваемые через сервер
videoRecorderToken (string) - Токен сервиса VideoRecorder. Требуется для доступа к API.
videoRecorderDecryptionKey (string) - Ключ шифрования сервиса VideoRecorder. Используется для защиты данных.
networksPath (string) - параметр, указывающий, откуда будут загружаться нейронные модели для детектирования лиц. По умолчанию используется значение '/networks/'.
iceServers (TIceServer[]) - объект с настройками WebRTC. Обязательное поле:
iceCandidateType: ('stun' | 'turn') - тип ICE кандидата.
ipAddress (string) - IP кандидата.
port (string) - порт кандидата.
iceCandidateTransport ('udp' | 'tcp') - Протокол, используемый для связи между клиентом и сервером.
livenessTransport ('HTTP' | 'WebRTC) - Этот параметр позволяет выбрать тип связи между клиентом и сервером (WebRTC или HTTP) при прохождении проверок на живость.
fingerprintWaitTime (number) - Этот параметр позволяет задать максимальное время ожидания сбора данных об окружении в котором совершается попытка. (По умолчанию - 2000 мс). Данные, которые не были получены в течение этого времени, не будут включены в конечный набор.
faceModelSettings (TFaceModelConfig) - объект с настройками нейронной модели для детектирования лиц.
modelEnabled (boolean) - флаг включающий нейросеть для детектирования лиц. Обратите внимание, что если вы отключите эту опцию, то настройка контроля движений больше не будет доступна. Кроме того, проверка живости будет запускаться автоматически через определенное время, указанное в параметре "Время ожидания перед стартом.
timeToStartRecord (number) - Время в миллисекундах, по истечении которого начнется проверка живости, если нейросеть для детектирования лиц отключена. Минимальное значение - 1000 мс.
cameraSettings (TCameraConfig) - объект с настройками камеры.
showCameraSelect (boolean) - флаг, включающий меню выбора камеры.
cameraResolution ('fhd' | 'hd' | 'sd') - Параметр, указывающий на «идеальное» разрешение видео. Ключ «fhd» означает разрешение 1920x1080, ключ «hd» - разрешение 1280x720, а ключ «sd» - разрешение 640x360. Этот параметр не указывает точное разрешение видеопотока, а лишь указывает разрешение, на которое будет ориентироваться браузер.
motionControl (boolean) - объект с настройками контроля движений. Доступны следующие поля:
enabled (boolean) - флаг включающий функцию контроля движений.
attemptsCount (number) - количество попыток, которые пользователь может предпринять для завершения контроля движений.
autoSubmit (boolean) - флаг, разрешающий автоматическую отправку запроса на проверку после прохождения liveness.
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 },
};
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 и сети.
Пример инициализации компоненты регистрации:
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');
},
},
}
);
Методы веб-компоненты
Destroy
Этот метод полностью демонтирует веб-компоненту.
Пример использования:
