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

# Попытка

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

Попытка не может существовать отдельно от аппликанта.

## Биометрические данные попытки​

Биометрические данные должны присутствовать в каждой попытке. Они отправляются вместе с запросом веб-компонентой или прямым запросом в publicapi.

Обязательные данные:

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

Необязательные данные:

- Видео liveness-reflection. Хранит в себе запись, на которой видны отражения света с экрана на лице. Видео используется для одноименной проверки liveness-reflection. Не требуется, если отключена проверка.

- Видео motion-control. Хранит в себе запись поворотов головы пользователем в соответствии с требуемыми паттернами движений. Видео используется для одноименной проверки motion-control. Не требуется, если отключена проверка.

## Проверки​

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

Некоторые проверки дополнительно содержат score — числовой показатель результата. Для таких проверок можно задать пороговое значение, после которого вердикт считается успешным.

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

### Места отображения результатов проверок​

В API результаты проверок отображаются в блоке validations. Если проверка проводилась, поле verdict содержит boolean-значение, отражающее результат. Если проверка не проводилась, verdict принимает значение null. Значение score проверки хранится в одноименном поле.

Пример проверки живости по фото в ответе API:

    "validations": {
        "liveness": {
            "verdict": true,
            "details": [
                {
                    "name": "FaceLiveness",
                    "verdict": true,
                    "score": 0.9999389,
                    "additionalInfo": {
                        "attackType": "none",
                        "attackTypeConfidence": 0.9999389
                    }
                },
                ...
            ]
        },
       ...
    }

Пример отображения проверки на дашборде:

- Если проверка успешна, значок проверки будет зеленым.
- Если проверка провалилась, значок проверки будет красным.
- Если проверка не проводилась, значок проверки будет серым.

### Список проверок​

Проверки подразделяются на три блока:

- живость (liveness): Проверки реальности биометрических данных.
- качество (quality): Проверки качества биометрических данных.
- cхожесть лица (matching): Сравнения лиц из биометрических данных.

Блок живости состоит из:

- Однокадровой живости. Живость лица из референсного кадра.
- Живости по видео (liveness-reflection). Живость лица из видео liveness-reflection (Экспериментальная функциональность)
- DeepFake. Проверка на наличие признаков использования технологии DeepFake. (Экспериментальная функциональность)

Блок качества состоит из:

- Проверки качества фото. Качество референсного кадра.

примечание

При провале проверки качества фото дополнительно к вердикту будут добавлены данные о причинах провала.

Список причин:

- Изображение слишком резкое.
- Изображение слишком шумное.
- Изображение имеет слишком высокий динамический диапазон.
- Лицо на изображении имеет большой угол наклона (pitch).
- Лицо на изображении имеет большой угол поворота (yaw).
- Лицо выходит за границу изображения.
- На лице обнаружены солнцезащитные очки.
- Размер лица на изображении слишком мал относительно самого изображения.

Блок схожести состоит из:

- Схожести лица. Схожесть лица из референсного кадра и лица из биометрии аппликанта при авторизации. Схожесть лица из референсного кадра и найденного дубликата из базы лиц при регистрации.

примечание

При провале проверки однокадровой живости дополнительно к вердикту и score будут добавлены данные о наиболее вероятном типе атаки и его confidence.

Список типов атак:

- replay: демонстрируется фото человека на каком-либо экране.
- photo: демонстрируется фото человека, не вырезанное по контуру.
- regions: демонстрируется вырезанное по контуру фото человека или только его лица.
- 2d-mask: демонстрируется вырезанное по контуру фото лица так, что оно "надето" на лицо реального человека.
- 3d-mask: демонстрируется 3D-маска.

## Метаданные​

Метаданные попытки - это данные об окружении пользователя, который сдавал биометрию, к примеру, ip адрес, таймзона устройства, тип устройства, версия браузера и т.д.

Метаданные используются для выявления некоторых рисков, но, в основном, носят справочный характер.

примечание

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

## Риски​

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

### Активный​

Cрабатывание риска приводит к провалу попытки.

Пример сработавшего риска в ответе API на запрос попытки:

    {
        "applicantId": "c9df2d99-9bba-4f4e-a967-ff215f80145b",
        "attemptId": 1014,
        ...
        "hasRiskEvents": true,
        ...
        "riskEvents": [
            {
              "created": "2025-03-06T10:49:10.630948Z",
              "riskNumber": 9,
              "riskName": "UntrustedIp",
              "isActive": true
            },
            {
              "created": "2025-03-06T10:49:10.630954Z",
              "riskNumber": 11,
              "riskName": "UntrustedDevice",
              "isActive": false
            }
        ],
    }

Пример сработавшего риска на странице попытки:

### Неактивный​

Cрабатывание риска приводит к его сохранению в попытку, но никак не влияет на вердикт попытки.

Пример сработавшего риска в ответе API на запрос попытки:

    {
        "applicantId": "c9df2d99-9bba-4f4e-a967-ff215f80145b",
        "attemptId": 1014,
        ...
        "hasRiskEvents": false,
        ...
        "riskEvents": [
            {
              "created": "2025-03-06T10:49:10.630948Z",
              "riskNumber": 9,
              "riskName": "UntrustedIp",
              "isActive": false
            },
            {
              "created": "2025-03-06T10:49:10.630954Z",
              "riskNumber": 11,
              "riskName": "UntrustedDevice",
              "isActive": false
            }
        ],
    }

Пример сработавшего риска на странице попытки:

### Выключенный​

Проверка риска полностью отключена в системе.

## Статусы попыток​

Статусы попытки говорят о том, какой был сделан вердикт при проверке переданных пользователем данных, а также какое было состояние системы на момент проверки этих данных.

### Места отображения статусов попытки​

В ответах API статус попытки хранится в поле status (численное представление). Пример ответа API, содержащий данные попытки:

    {
      "applicantId": "78c57b83-9420-404e-bc7e-9edd1c131e55",
      "attemptId": 128,
      ...
      "status": 1
    }

В дашборде статус выбранной попытки можно увидеть в детальной информации по аппликанту:

### Описание статусов попытки​

Новая попытка создается в момент начала сессии пользователя и получает статус Unfinished. При корректном завершении сессии статус попытки обновляется в соответствии с результатами.

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

Название статуса | Номер статуса | Описание статуса
Success | 0 | Данные попытки успещно прошли все проверки
Fail | 1 | Данные попытки провалили какую-либо проверку
InvalidData | 2 | Данные проверки не соответствуют требуемым. Например, отсутствует лицо на референсном фото или отсутствуют записанные видео, хотя они требовались.
Error | 3 | При обработке попытки произошла ошибка на сервере
Unfinished | 4 | Сессия пользователя начата, но еще не завершена

примечание

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