Перейти к основному содержимому

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

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

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

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

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. После установки пакета переместите папки images networks из /node_modules/@tdvc/face-onboarding/ и frame_handler_worker.js из /node_modules/@tdvc/face-onboarding/dist в директорию public.

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

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

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

    import tdvc, {
        ComponentSettingsFromClient,
        TDVAthorizationOnboarding,
        TDVRegistrationOnboarding,
    } from '@tdvc/face-onboarding';
    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: (referenceImage: string) => void`; — функция, которая вызывается после получения ключевого кадра. referenceImage - изображение в формате строки 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.15.* | 1.15.*
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