Веб-компонента

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

Принцип работы

Полный алгоритм работы выглядит следующим образом:

1. Веб-компонента инициализируется.

   Веб-компонента принимает две конфигурации: одну — от фронтенда проекта, в который она интегрирована, а другую — от сервера BAF через его API. После этого обе конфигурации объединяются в одну.

   При совпадении параметров в конфигурациях клиента и сервера приоритет отдаётся значению из конфигурации клиента.

   После объединения веб-компонента инициализирует необходимые сервисы для работы: детектор лиц, механизмы записи видео и другие.

2. Веб-компонента определяет присутствие пользователя в системе BAF и его текущий статус.

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

   После определения пользователя выполняется проверка его статуса в системе BAF. Если статус валиден, пользователь допускается к следующему этапу, в противном случае веб-компонента отобразит ошибку о недопустимом статусе и заблокирует дальнейший путь пользователя.

   Если уникальный идентификатор пользователя был передан через конфигурацию, то форма не отображается, а сразу выполняется проверка статуса.

3. Веб-компонента получает доступ к веб-камере устройства пользователя.

   Веб-компонента запрашивает доступ к камере устройства. Если разрешение получено и хотя бы одна из камер доступна, отображается видеопоток, в противном случае выводится сообщение об ошибке. При наличии нескольких камер пользователю предоставляется возможность выбора.

4. Этап биометрической проверки "Motion Control".

   Веб-компонета генерирует несколько команд, которые пользователь должен выполнить перед камерой. В набор команд входят следующие действия: повернуть голову влево, повернуть голову вправо, поднять голову, приблизиться к камере, отдалиться от камеры.

   Во время проверки происходит отбор кадров, содержащих лицо пользователя, которые будут использованы для ряда дополнительных проверок на стороне сервера, таких как живость лица, качество изображения и другие.

5. Этап биометрической проверки лица пользователя.

   Вспомогательный этап, который используется, если биометрическая проверка "Motion Control" оключена.

   На этом этапе веб-компонета фиксирует положение головы пользователя и производит отбор кадров лица пользователя, которые будут использованы для ряда дополинтельных проверок на стороне сервера, таких как живость лица, качество изображения и другие.

6. Этап валидации собранных данных и результатов биометричеких проверок.

   Веб-компонета генерирует отпечаток устройства пользователя, отправляет все собранные данные на сервер и получает от него оценку пути пользователя.

Установка веб-компоненты

Компонента поставляется в виде архива TGZ tdvc-face-onboarding. Также для работы потребуется библиотека tdvc, которая также поставляется в виде архива.

1. Переместите архивы в корневую папку вашего проекта и добавьте следующие строки в ваш package.json в разделе зависимостей:

   "@tdvc/face-onboarding": "file:tdvc-face-onboarding-{version}.tgz"

   Версия архива может отличаться. Пример итогового файла package.json:

   "dependencies": {
       "@tdvc/face-onboarding": "file:tdvc-face-onboarding-1.0.0.tgz"
   }

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

3. Для корректной работы веб-компоненты необходимо добавить ряд файлов в директорию, где хранятся статические ресурсы вашего проекта, обычно это директория public. После установки пакета переместите папку networks из /node_modules/@tdvc/face-onboarding/ и frame_handler_worker.js из /node_modules/@tdvc/face-onboarding/dist в директорию public.

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

1. Импортируйте библиотеку и стили для нее.
2. Создайте интеграцию веб-компоненты на сервере.
3. Определите конфигурацию веб-компоненты.
4. Запустите проект.

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

import tdvc from '@tdvc/face-onboarding';
import {
    TDVAthorizationOnboarding,
    TDVRegistrationOnboarding,
} from '@tdvc/face-onboarding/dist/class';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration';
import '@tdvc/face-onboarding/dist/css/style.css';

let lib: TDVRegistrationOnboarding | TDVAthorizationOnboarding;

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
};

function run() {
    if (window.location.pathname === '/registration') {
        lib = new tdvc.Register(config);
    } else {
        lib = new tdvc.Authorization(config);
    }
}

window.onload = async () => {
    run();
};

window.onbeforeunload = () => {
    lib?.destroy();
};

Взаимодействие веб-компоненты с внешней системой

Взаимодействия между веб-компонентой и внешней системой осуществляется через функции обратного вызова (колбеки). Система определяет свою логику обработки событий на основе данных из этих функций или самого факта их вызова. В конфигурации компоненты определен ряд таких функций:

1. onMounted: (() => void) — функция, которая вызывается когда веб-компонета полностью инициализирована.

2. onError: ((message: string, code: string) => void) — функция, которая вызывается, если во время прохождения пользовательского пути произошла ошибка.

3. onUpdate: (() => void) — функция, которая вызывается, если после возникновения ошибки пользователь хочет попробовать еще раз пройти пользовательский путь.

4. onIdentifyApplicantStatus: (applicant: {applicantId: string, status: number}) => void — функция, которая вызывается после получения статуса аппликанта от сервера.

5. onBack: (() => void) — функция, которая вызывается, если пользователь нажал кнопку "Назад" во время выбора камеры, и тем самым откзалася от прохождения пользовательского пути.

6. onMotion: ((type: 'left' | 'right' | 'up' | 'closer' | 'farther' | 'return', result: boolean | undefined) => void) - функция, которая вызывается во время проходения биометрической проверки "Motion Control". result = undefined означает, что проверка только началась, true — успешно пройдена, а false — провалена.

7. onGetReferenceImages: (referenceImages: string[]) => void; — функция, которая вызывается, когда собраны лучшие кадры лица. referenceImages - изображения в формате base64 строки.

8. onStartValidation: (() => void) — функция, которая вызывается перед началом валидации результатов.

9. onValidate: ((data: any) => void) — функция, которая вызывается после получения результата валидации данных от сервера.

Локализация

По умолчанию веб-компонента поддерживает две локализации — русскую и английскую, при этом язык интерфейса по умолчанию — английский. Локализацию можно изменить через конфигурацию при инициализации веб-компоненты, указав поля language и locale.

Пример изменения английской локализации на TypeScript:

import tdvc from '@tdvc/face-onboarding';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration'

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
    locales: {
        // Если требуется оставить русскую локализацию по умолчанию
        ...tdvc.DefaultLocales.ru,
        // Рeдактирование английской локализации
        en: {
            // Оставляем другие данные данной локализации по умолчанию
            ...tdvc.DefaultLocales.en,
            Login: {
                // Оставляем другие локали данного блока по умолчанию
                ...tdvc.DefaultLocales.en.Login,
                // Редактируем нужное сообщение
                IsRequired: 'New locale message',
            },
        },
    },
};

Для добавления новой локализации подготовьте объект Java Script, который будет содержать все те же самые поля, что и объект с английской локализацией. Для каждого идентификактора сообщения определите текст на требуемом языке. Объект локализации, который можно использовать в качестве примера, можно найти в файле README.md в архиве поставки.

Пример добавления новой локализации на TypeScript:

import tdvc from '@tdvc/face-onboarding';
import { ComponentSettingsFromClient } from '@tdvc/face-onboarding/dist/class/configuration'

const config: ComponentSettingsFromClient = {
    mountElement: 'app',
    baseUrl: '/',
    integrationId: '225c74bb-4eb1-4c81-9199-832dff3806eb',
    language: 'fr',
    locales: {
        // Если требуется оставить русскую и английскую локализацию по умолчанию
        ...tdvc.DefaultLocales,
        // Ключ объекта должен совпадать со значением в поле language
        fr: {
            Login: {
                IsRequired: 'Nouveau message de paramètres régionaux',
                ...
            },
            ...
        },
    },
};

Стилизация

Стилизация веб-компоненты осуществляется через CSS. Элементы интерфейса содержат идентификаторы и CSS классы, через которые можно кастомизировать их внешний вид.

Идентификаторы и СSS классы, которые используются для кастомизации, можно посмотреть в файле @tdvc/face-onboarding/dist/css/style.css

Таблица совместимости версий сервера и веб-компоненты:

BAF	@tdvc/face-onboarding
1.14.*	1.14.*
1.13.*	1.13.*
1.12.*	1.12.*
1.10.*	1.10.*-1.11.*
1.9.*	1.9.*
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