Перейти к основному содержимому
Версия: 1.3.1

Работа с Web-компонентой

Web-компонента — это инструмент захвата изображений, с помощью которого пользователь может выполнять регистрацию и авторизацию через веб-интерфейс. Обратите внимание, что Web-компонента работает только в браузерах, основанных на Chromium.

Доступны две версии Web-компоненты. Одна предназначена для работы со сценариями распознавания лиц (поддерживает новую бета-версию подсистемы LRS). Вторая предназначена для совместной проверки изображений лиц и документов.

Таблица совместимости версий:

BAF@tdvc/face-onboarding@tdvc/document-onboarding
1.0.01.0.01.0.0
1.1.01.0.0-1.1.21.0.0
1.2.01.2.0-1.3.01.0.0
1.3.0-1.3.11.3.11.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:

img.png

После этого вызовите команду npm install, которая установит библиотеку в ваш проект.

Импорт и использование Web-компоненты

Импортируйте библиотеку, а также стили для нее. При желании стилизация может быть переписана пользователем. Пример импорта библиотеки и стилей:

img.png

Теперь инициализируйте Web-компоненту. Для этого заполните файл конфигурации, подробное описание которого можно посмотреть ниже:

Web-компонента предоставляет два модуля: регистрацию и авторизацию. Чтобы использовать Web-компоненту, создайте экземпляр нужного вам модуля TVDOnboarding.
Каждый модуль принимает в качестве параметров три объекта конфигурации. Ниже приведено описание каждой конфигурации:

serverConfig

  • baseUrl (string) — URL-адрес 3DiVi BAF (обязательное поле).

  • 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) — флаг, разрешающий выбор камеры (обязательное поле).

  • motionControlEnabled (boolean) - флаг включающий функцию проверки движений.

  • callbacks (object) - объект с функциями обратного вызова. Доступны следующие функции:

    • onValidate ((data: any) => void) - функция, которая будет вызываться после получения ответа проверки. Возвращаемое значение — это объект с информацией проверки.

    • onError ((message: string, code: string) => void) - функция, которая будет вызываться в случае ошибки. Значением ответа является объект с сообщением ошибки.

  • 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-компоненту.

Пример использования: img.png

С документами

Дальнейшие инструкции по установке и настройке 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:

img.png

После этого вызовите команду npm install, которая установит библиотеку в ваш проект.

Импорт и использование Web-компоненты

Импортируйте библиотеку, а также стили для нее. При желании стилизация может быть переписана пользователем. Пример импорта библиотеки и стилей:

img.png

Теперь инициализируйте 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 — функция обратного вызова, которая будет вызвана после выполнения всех шагов. Возвращаемое значение — это объект со следующим содержимым:

img.png

Пример инициализации Web-компоненты:

img.png

Методы web-компоненты

Restart

Метод restart полностью перезапускает Web-компоненту с той же конфигурацией, с которой она была инициализирована.

Пример использования: img.png

Set applicant

Метод setApplicant перезапускает компоненту с переданным аппликантом и с той же конфигурацией, с которой она была инициализирована.

Пример использования: img.png

Update config

Метод updateConfig перезапускает компоненту с переданной конфигурацией.

Пример использования: img.png