Работа с Веб-компонентой
Веб-компонента — это инструмент захвата изображений, с помощью которого пользователь может выполнять регистрацию и авторизацию через веб-интерфейс.
Таблица совместимости версий:
| BAF | @tdvc/face-onboarding |
| 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 |
Установка веб-компоненты
Компонента поставляется в виде архива 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. Обязательное поле.
applicantId (string) - ID applicant-а для регистрации или авторизации.
Обратите внимание, что в конфигурации должно быть только одно из двух полей: applicantId или applicantFields.
mountElement (string) - Id элемента на странице, в который будет интегрирован компонент. Обязательное поле.
language (string) - текущий язык интерфейса. Если значение не указано, то по умолчанию будет использоваться «en».
locales (Locales) - пользовательские локали для изменения текстов. Для удобства использования мы рекомендуем записать один файл с локалями и использовать его во всех конфигурациях компоненты. Если значение не указано, будет использован объект по умолчанию.
Принимаемое значение - объект со следующим содержимым:
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) - функция, которая будет вызываться после инициализации компоненты. Эта функция не возвращает значение.
Поля, которые по умолчанию берутся с сервера и могут быть перезаписаны на стороне клиента
Чтобы перезапись настроек заработала необходимо включить соответствующую настройку в интеграции веб-компоненты.
livenessTransport ('LivenessTransport.WEB_SOCKET' | 'LivenessTransport.WEB_RTC') - этот параметр позволяет выбрать тип связи между клиентом и сервером (WebRTC или WebSocket) для записи видео.
fingerprintWaitTime (number) - этот параметр позволяет установить максимальное время ожидания сбора данных для создания отпечатка устройства. По умолчанию 2000 мс. Данные, которые не были получены в течение этого времени, не будут включены в отпечаток.
faceModelSettings (FaceDetectorSettings) - объект с настройками сетки лица.
modelEnabled (boolean) - флаг, включает сетку для лица. Обратите внимание, что если вы отключите эту опцию, функция Motion Control будет недоступна. Кроме того, видеозапись Liveness Reflection начнется через определенное время. По умолчанию это значение равно true.
timeToStartRecord (number) - время в миллисекундах, через которое начнется запись видео Liveness Reflection, если сетка лица выключена.
cameraSettings (CameraSettings) - объект с настройками камеры.
showCameraSelect (boolean) - флаг, включающий выбор камеры.
cameraResolution ('CameraResolutions.FULL_HD' | 'CameraResolutions.HD' | 'CameraResolutions.SD') - Параметр, указывающий на «идеальное» разрешение видео. Ключ «FULL_HD» означает разрешение 1920x1080, ключ «HD» - разрешение 1280x720, а ключ «SD» - разрешение 640x360. Эта настройка не указывает точное разрешение видеопотока, а лишь указывает разрешение, к которому будет стремиться браузер. По умолчанию используется значение «HD».
cameraId (string) - ID используемой камеры.
motionControl (MotionControlSettings) - объект с настройками Motion Control. Доступны следующие поля:
enabled (boolean) - флаг, включающий запись видео Motion Control.
attemptsCount (number) - количество попыток, которые пользователь может предпринять для записи Motion Control.
order (number) - порядок проверок. Только для WebSocket Если значение совпадает со значением «order» в объекте «livenessReflection», то сначала будет проверен Liveness Reflection.
livenessReflection (LivenessReflectionSettings) - объект с настройками Liveness Reflection. Доступны следующие поля:
enabled (boolean) - флаг, включающий Liveness Reflection. Только WebSocket
order (number) - порядок проверок. Только WebSocket
autoSubmit (boolean) - флаг, включающий автоматическую отправку запроса на проверку после прохождения проверок.
applicantFields (ApplicantFields) - настройка полей аппликанта, которые должны отображаться при регистрации или авторизации. Значения этих полей будут отправлены в запрос на создание аппликанта. Primary поле определяет, по какому ключу будет выполняться поиск аппликанта в базе данных. Обратите внимание, что primary поле должно быть единственным и включенным. Принимаемое значение представляет собой объект со следующим содержимым:
applicantFields: {
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 (FaceSettings) - объект с настройками зоны распознавания. Эта настройка позволяет регулировать размер отображаемой окружности лица. Эта настройка также влияет на размер лица, при котором начинается видеозапись. Размеры вложенных объектов отвечают за размер стандартного круга. Окружность для шаблона "ближе „ определяется параметром closerPercent, а для шаблона “farther » параметром является fartherPercent. Параметры closerPercent и fartherPercent показывают, насколько окружность будет больше или меньше стандартной. Параметр sizeAccuracy отвечает за допустимую разницу в размерах отображаемого круга лица и BBox (измеряется в пикселях). Пример объекта с настройками (значения, указанные в примере, являются значениями по умолчанию):
faceSettings: {
sizes: {
mobile: {
width: 1.2,
height: 0.6,
},
pc: {
sd: {
width: 0.6,
height: 0.9,
},
hd: {
width: 0.6,
height: 0.9,
},
fhd: {
width: 0.4,
height: 0.6,
},
},
},
closerPercent: 115,
fartherPercent: 85,
sizeAccuracy: 60,
}
showMetrics (boolean) - Флаг, позволяющий отображать метрики соединения WebRTC: FPS и сеть (только для WebRTC).
obtainReferenceFrame (boolean) - Флаг, позволяющий получать референсный кадр для видео.
networksPath (string) - параметр, указывающий, откуда будут загружаться модели FaceMesh. По умолчанию используется значение '/networks/'.
Пример инициализации компоненты регистрации:
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
Этот метод полностью демонтирует веб-компоненту.