Работа с Web-компонентой
Web-компонента — это инструмент захвата изображений, с помощью которого пользователь может выполнять регистрацию и авторизацию через веб-интерфейс. Обратите внимание, что Web-компонента работает только в браузерах, основанных на Chromium.
Доступны две версии Web-компоненты. Одна предназначена для работы со сценариями распознавания лиц (поддерживает новую бета-версию подсистемы LRS). Вторая предназначена для совместной проверки изображений лиц и документов.
Таблица совместимости версий:
| 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 |
Без документов
Дальнейшие инструкции по установке и настройке Web-компоненты подходят при использовании BAF без документов. В этом случае вам необходимо использовать Web-компоненту tdvc-face-onboarding.
Установка 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-адрес 3DiVi BAF. Если вы передатите в качестве значения "/", то все запросы будут отправляться на хост, на котором развернута Web-компонента (обязательное поле).
bafToken (string) — Секретный ключ веб-API BAF (обязательное поле).
platformToken (string) — токен доступа к OMNI Platform (обязательное поле).
lrsToken (string) — токен доступа к Liveness Reflection(обязательное поле).
lrsDecryptKey (string) — ключ дешифровки для Liveness Reflection (обязательное поле).
iceServers (TIceServer[]) — объект с настройками WebRTC (обязательное поле).
ip (string) — IP stun сервера (обязательное поле).
port (string) — порт stun сервера (обязательное поле).
transport ('udp' | 'tcp') — протокол stun сервера (обязательное поле).
blConfig
showCameraSelect (boolean) — флаг, разрешающий выбор камеры (обязательное поле).
autoSubmit (boolean) - флаг, включающий автоматическое отправление запроса на валидацию после прохождения liveness.
motionControlEnabled (boolean) - флаг включающий функцию проверки движений.
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, функция была вызвана в начале шаблона, в противном случае — в конце.
applicationFields (TApplicantConfiguration) - настройка полей аппликанта, которые должны отображаться при регистрации или авторизации. Значения этих полей будут отправлены в запрос на создание аппликанта. Primary поле определяет, по какому ключу будет искаться аппликант в базе данных. Обратите внимание, что основное поле должно быть только одно, и оно должно быть включено. Принимаемое значение представляет собой объект со следующим содержимым:
```javascript
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-компонента (обязательное поле).
language (string) — текущий язык (обязательное поле).
locales (TLocales) — пользовательские локали для изменения текстов. Для удобства использования рекомендуем написать один файл с локалями и использовать его во всех конфигурациях Web-компоненты. В качестве принимаемого значения необходим объект со следующим содержимым:
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',
},
},
}
};
Пример инициализации компоненты регистрации:
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
);
Методы Web-компоненты
Destroy
Этот метод полностью демонтирует Web-компоненту.
Пример использования:
С документами
Дальнейшие инструкции по установке и настройке Web-компоненты подходят при использовании BAF с документами. В этом случае вам необходимо использовать Web-компоненту tdvc-document-onboarding.
Установка Web-компоненты
Web-компонента поставляется как npm-пакет в составе BAF в виде .tgz архива. Для установки Web-компоненты поместите ее в корень вашего проекта рядом с файлом package.json.
В package.json в раздел dependencies добавьте строку:
"@tdvc/document-onboarding": "tdvc-document-onboarding-{version}.tgz".
Версия архива может отличаться. Пример итогового файла package.json:
После этого вызовите команду npm install, которая установит библиотеку в ваш проект.
Импорт и использование Web-компоненты
Импортируйте библиотеку, а также стили для нее. При желании стилизация может быть переписана пользователем. Пример импорта библиотеки и стилей:
Теперь инициализируйте Web-компоненту. Для этого заполните файл конфигурации, подробное описание которого можно посмотреть ниже:
Описание конфигурации Web-компоненты
el (string) — ID элемента на странице, куда интегрируется Web-компонента (обязательное поле).
applicantId (string) — ID аппликанта (обязательное поле).
domainId (string) — ID домена, содержащего настройки и стили для Web-компоненты (обязательное поле).
domainApi (string) — URL адрес для доступа к API (обязательное поле).
publicKey (string) — публичный ключ для доступа к API (обязательное поле).
isAuth (boolean) — флаг указывающий, что необходима только авторизация пользователя.
faceOnly (boolean) — флаг указывающий, что регистрация и авторизация должны быть только по лицу.
chunkPublicPath (string) — путь к папке с чанками. Укажите путь на сервере, если вам нужно переместить папку в другое место. Путь по умолчанию — 'networks'.
networkUrl (string) — путь к папке с нейросетями. Укажите путь на сервере, если вам нужно переместить папку в другое место. Путь по умолчанию — 'networks'.
useCDN (boolean) — флаг включается, если вы хотите загружать 'networks' с CDN, а не со своего домена.
preferApiConfig (boolean) — флаг включается, если вы предпочитаете использовать конфигурацию библиотеки TDV, отправленную из BAF API, вместо конфигурации, использованной при инициализации оболочки.
hideDocumentTitle (boolean) — эта опция включает/отключает отображение заголовков документов.
processingImageFormat (string) — эта опция переключает формат изображения, используемый для обработки изображения.
callbacks (object) — объект с функциями обратного вызова. Доступны следующие функции:
onChange — функция обратного вызова, которая будет вызываться после прохождения каждого шага. Возвращаемое значение — это объект с типом и изображением.
onCameraError — функция, вызываемая в случае, если камера недоступна. Значением ответа является объект с кодом ошибки и сообщением.
onReset — функция обратного вызова, которая будет вызываться после сброса всех шагов. Возвращаемое значение — это объект с шагами.
onRetakeHook — функция, которая будет вызываться перед сбросом текущего шага. Возвращаемое значение — это объект с текущим шагом.
onValidate — функция, которая будет вызываться после получения ответа проверки. Возвращаемое значение — это объект с информацией проверки.
onError — функция, которая будет вызываться в случае ошибки. Значением ответа является объект с кодом ошибки и сообщением.
onReloaded — функция, которая будет вызвана после завершения перезагрузки компоненты. Эта функция не возвращает значение.
onMounted — функция, которая будет вызываться на смонтированной компоненте. Эта функция не возвращает значение.
submit — функция обратного вызова, которая будет вызвана после выполнения всех шагов. Возвращаемое значение — это объект со следующим содержимым:
Пример инициализации Web-компоненты:
Методы web-компоненты
Restart
Метод restart полностью перезапускает Web-компоненту с той же конфигурацией, с которой она была инициализирована.
Пример использования:
Set applicant
Метод setApplicant перезапускает компоненту с переданным аппликантом и с той же конфигурацией, с которой она была инициализирована.
Пример использования:
Update config
Метод updateConfig перезапускает компоненту с переданной конфигурацией.
Пример использования:
