Liveness и сравнение лиц также могут производиться с помощью модуля Oz API Lite. Этот модуль принципиально отличается от Oz API.

• Никакие данные нигде не сохраняются,

• Очень просто масштабировать горизонтально,

• Отсутствует аутентификация и нельзя управлять доступом,

• Работает только с изображениями.

Oz API Lite рекомендуется использовать для встраивания в ваш продукт при высоких требованиях к производительности (миллионы проверок в неделю).

В версиях SDK для Android и iOS 8.0.0 мы добавили новый режим анализа – гибридный. Это комбинация анализов на устройстве и на сервере, сочетающая в себе плюсы обоих подходов. Если анализ на устройстве дает неоднозначный результат по поводу присутствия живого человека в кадре, система запускает анализ на сервере, в ином случае никаких дополнительных проверок не проводится.

Преимущества гибридного анализа

Требования к вычислительной мощности ниже: в большинстве случаев анализа на устройстве достаточно, так что проверки на сервере не нужны, количество запросов также сокращается. На Android перепроверка требуется 8-9% анализов, на iOS – 4,5-5,5%.

Точность гибридного анализа практически такая же, как серверного: неоднозначный результат анализа на устройстве ведет к проверке на сервере.

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

С релизом 8.3.0 появилось дополнительное преимущество – анализ выполняется быстрее, а данных передается меньше. Поскольку в большинстве случаев анализ на устройстве дает точный результат, загружать полноразмерное видео на сервер для анализа нужно редко, так что дополнительной передачи данных в большинстве случаев не требуется. Путь ваших клиентов станет короче.

Как включить гибридный режим анализа

Для запуска гибридного анализа нужна версия наших мобильных SDK 8.0.0 или выше. При этом серверный анализ будет запускаться в меньшинстве случаев, поскольку однозначный результат анализа на устройстве означает ненужность «второго мнения» от сервера – соответственно, ресурсов сервера потребуется меньше.

Цель проверки Liveness – подтвердить, что перед камерой находится реальный человек. Для пассивной проверки Liveness достаточно того, чтобы этот человек просто смотрел в камеру. Активная проверка подразумевает, что человек перед камерой также делает какой-то жест – например, улыбается, моргает или поворачивает голову. Пассивная проверка проще для пользователя, однако активная также может быть полезна в некоторых ситуациях – например, когда необходимо убедиться, что пользователь в курсе прохождения им Liveness-проверки.

В наших мобильных SDK, а также в Web SDK вы можете установить, что именно должен сделать пользователь перед камерой. Можно также объединить несколько действий в последовательность. Действия различаются по:

• сложности для пользователя,

• размеру итогового файла,

• точности проверки Liveness,

• возможности перепроверки результата оператором-человеком или в суде.

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

Пассивный Liveness

Активный Liveness

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

Oz API

Oz API – центральный компонент системы, RESTful API-интерфейс для доступа к основной функциональности анализов Liveness и Face Matching. Преимущества Oz API:

• Сохранение данных – ваши медиафайлы и анализы хранятся для будущего использования, пока вы самостоятельно их не удалите.

• Возможность работать и с фото, и с видео.

• Асинхронность анализов.

• Безопасная аутентификация.

• Гибкая настройка уровней доступа.

«Под капотом» Oz API работают следующие компоненты:

• Хранилище файлов и база данных, где сохраняется информация о медиафайлах, анализах и так далее,

• Модуль Oz BIO – он отвечает за работу специально обученных нейронных сетей, распознающих лица,

• Логика лицензирования.

Фронтенд-компоненты, такие как мобильные или Web SDK, подключаются к Oz API в процессе обработки серверных анализов. Они могут это делать и напрямую, и через бэкенд клиента.

iOS и Android SDK

iOS и Android SDK вместе называются мобильными (или нативными) SDK. Первый написан на SWIFT, второй – на Kotlin/Java. Оба они созданы для интеграции в ваши мобильные приложения.

Интерфейс мобильных SDK легко и гибко настраивается под ваши нужды, не влияя на основную функциональность: удобный для пользователей процесс съемки видео в оптимальном для последующих анализов качестве.

После записи Liveness-видео вы можете запустить анализы или на сервере, или на устройстве.

Web SDK

Web SDK состоит из Web Adapter и Web Plugin. Web SDK также разработан для интеграции в ваше приложение – в его веб-версию. Функциональность Web SDK аналогична таковой для iOS и Android: удобный для пользователей процесс съемки видео в оптимальном для последующих анализов качестве.

Web Adapter – часть Web SDK, которая устанавливается и конфигурируется на сервере. Web Plugin работает в контексте браузера: его вызывает ваше веб-приложение. Plugin взаимодействует с Adapter, а тот. В свою очередь – с Oz API. Дополнительное преимущество Web Plugin – защита от инъекционных атак:

1. Обнаружение атак путем сбора информации о контексте браузера и свойствах камеры – таким образом можно засечь виртуальную камеру или другие инструменты инъекционных атак.

2. Запись видео в формате, в котором запущенные на сервере нейронные сети могут наиболее эффективно отследить атаку в уже записанном видео.

Web UI (веб-консоль)

Oz Forensics специализируется на проверках Liveness и Face Matching (сравнении лиц): мы разрабатываем продукты, которые помогают вам удаленно идентифицировать ваших клиентов и защищаться от любых видов спуфинга – презентационных и инъекционных атак, в том числе 3D-масок, дипфейков, атак вида MITM. Вы можете добавить в свое программное обеспечение Liveness, Face Matching или и то, и другое в зависимости от того, какие именно проверки вам нужны и в каком объеме. Мы постоянно совершенствуем наши компоненты, повышая их качество и надежность их работы.

Oz Liveness

• Oz Liveness распознает лицо живого человека в полученном медиафайле. Алгоритм отличает реального человека в сознании от спящего, маски, фотографии, видеоролика с изображением лица и других видов спуфинг-атак. Поддерживаются мобильные и десктопные устройства. Алгоритм сертифицирован по стандарту ISO-30137-3 и прошел тест iBeta лаборатории NIST со 100% точностью.

Наша технология Liveness защищает и от инъекционных, и от презентационных атак.

Обнаружение инъекционных атак происходит в два этапа. Сперва наш SDK проверяет среду пользователя: нет ли манипуляций с браузером, камерой, и так далее. Затем готовый медиафайл анализируют нейронные сети, обеспечивая надежную защиту даже от самых сложных инъекционных атак.

Вероятность наличия презентационной атаки мы проверяем с помощью нейронных сетей различных архитектур, используя при этом собственные алгоритмы ансамблирования для оптимальной продуктивности. На результат работы сетей влияет множество факторов: свет, отражение, четкость картинки, фон, паттерны движения и другие. Наш Liveness работает как с пассивными (без жестов), так и с активными (различные жесты) проверками – чтобы вашим клиентам было удобно эти проверки проходить, а вы при этом получали достоверные результаты. Тест iBeta проводился на пассивном Liveness, и с тех пор мы значительно улучшили качество наших проверок.

Oz Face Matching (Biometry)

• Oz Face Matching (Biometry) проводит биометрическую идентификацию человека, проверяя, принадлежит ли документ человеку, проходящему проверку, на основе биометрического сходства лиц. Модуль находит лучший кадр в снятом видео и сравнивает его с фотографией из документов. Точность в 99,99% подтверждена NIST FRVT.

Наши технологии основаны на алгоритмах машинного обучения. Мы поддерживаем и верификацию (1:1, Face Verification), и идентификацию лица (1:N, Face Identification). Для обучения нейронных сетей мы используем собственный фреймворк, построенный на новейших технологиях. Собственная база данных содержит более 4,5 миллионов уникальных лиц. В ней представлены различные этнические группы, кроме того, мы учитываем предполагаемые расу, возраст и т.д. Все это помогает нашим биометрическим моделям обеспечивать достоверные результаты сопоставления.

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

Программное обеспечение Oz сочетает точность анализа с легкостью интеграции и использования. Чтобы дополнительно упростить процесс интеграции, мы предоставили подробное описание всех ключевых концепций нашей системы в этом разделе. Если вы готовы начать, обратитесь к нашим руководствам по интеграции: мы подготовили пошаговые инструкции, которые помогут вам легко и быстро встроить проверки Liveness и Face Matching в ваше ПО.

В этом разделе собраны описания наиболее часто встречающихся примеров интеграции системы Oz Forensics Liveness and Face Biometry. Сценарии могут как использоваться по отдельности, так и комбинироваться – например, интеграция Liveness сразу и в мобильное, и в веб-приложение или интеграция и Liveness-решения, и решения для сравнения лиц.

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

• Liveness проверяет наличие живого человека на фото или видео.

• Face Matching сравнивает два или более медиафайла, определяя уровень сходства между запечатленными на фото или видео людьми.

• Black list ищет сходства между лицом человека, запечатленного на фото или видео, и лицами в заранее созданной базе фотографий.

Liveness

Проверка Liveness используется для защиты от двух видов атак.

Презентационная атака (или спуфинг-атака) – это попытка человека обмануть систему распознавания лиц «физически», демонстрируя камере видеоролик, фотографию или другой тип медиафайла, лицо на котором похоже на лицо нужного человека. К презентационным атакам относятся также использование реалистичных масок или грима.

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

Oz Liveness распознает оба типа атак:

• презентационные атаки – с помощью любых компонентов,

• инъекционные атаки – с помощью Oz Liveness SDK.

Подробная информация о том, как противостоять описанным атакам, содержится в наших руководствах по интеграции:

По завершении проверки Liveness вы можете оценить качественные и количественные результаты.

Также при проверке Liveness может сохраняться best shot (лучший кадр) – это наиболее качественный кадр из всего видео, изображение, на котором лучше всего видно лицо.

Face Matching (сравнение лиц)

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

Black list (черный список)

В Oz API вы можете создать один или более черных списков, каждый из которых представляет собой коллекцию изображений лиц – то есть базу данных фотографий. Black list проводит сравнение лица с только что сделанного фото или только что снятого видео с лицами из этой базы данных и показывает, присутствует ли в ней этот человек.

Мы предлагаем различные модели использования компонентов Oz – в зависимости от ваших надобностей и предпочтений. Вы можете подключиться к одному из наших облаков и работать с SaaS или интегрировать наши компоненты в свою инфраструктуру – система функционирует одинаково, какую бы модель взаимодействия с ней вы ни предпочли. Здесь мы приводим несколько советов по выбору.

Когда лучше выбрать SaaS

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

• Быстрый старт. Вам не нужно приобретать оборудование или выделять ресурсы для системы.

• Нулевые затраты на инфраструктуру. Мы обеспечиваем все необходимые серверные компоненты.

• Низкая стоимость обслуживания. Свое оборудование мы обслуживаем и обновляем сами.

• Данные не отправляются за границу вашей страны. Это актуально для регионов расположения наших облаков.

Когда лучше выбрать локальную установку на ваш сервер

В случае локальной установке все компоненты системы встраиваются в вашу инфраструктуру. Вы получаете:

• Полный контроль над конфигурацией,

• Хранение и обработку данных внутри вашей инфраструктуры – «наружу» информация не передается.

Когда лучше выбрать анализ на устройстве

Анализом на устройстве вы можете воспользоваться в наших мобильных SDK для анализов Liveness и Face Matching. Применим такой анализ, например, в следующих случаях:

• Медиафайлы с лицами представляют собой конфиденциальные данные и вы никуда не можете их пересылать.

• Вы планируете использовать наши продукты в регионах с плохим покрытием интернет-сетями.

Какую модель выбрать, решаете только вы. Мы всегда готовы оказать помощь как в выборе, так и в сопровождении.

Oz API обеспечивает полноценный REST API-интерфейс для биометрии лица: как сравнения лиц, так и Liveness-проверок. В этой статье описаны основные концепции Oz API.

Аутентификация, роли пользователей и управление доступом

Сохранение данных

Основная сущность в Oz API – это папка (заявка): в папку вы можете загружать медиафайлы, запускать для них анализы и получать результаты не только для отдельных анализов, но и для папки в целом. В одной папке может быть любое количество медиафайлов, для каждого из которых можно назначить любое количество анализов. Анализы также могут назначаться для нескольких медиафайлов сразу.

Типы медиафайлов и теги

Oz API работает и с фото-, и с видеофайлами. Видео при этом может быть как файлом в «обычном» понимании, то есть контейнером в формате MP4 или MOV, так и последовательностью кадров в ZIP-архиве. Чтобы определить тип медиафайла, Oz API использует MIME-тип файла.

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

• photo_id_front – для лицевой стороны документа

• photo_selfie – для референтного фото, не являющегося документом

• video_selfie_blank – для Liveness-видео, снятого не средствами Oz Liveness SDK

• если фото или видео снято средствами нашего SDK, теги выставляются автоматически

Асинхронные анализы

Для коммерческого использования нашего продукта необходима лицензия. Она определяет, какими функциями нашего ПО вы можете пользоваться – в соответствии с условиями договора. Лицензия выдается на ограниченное время и по необходимости продлевается.

Когда вы запускаете наши SDK или пользуетесь Oz BIO, система проверяет валидность лицензии. Это происходит в фоновом режиме и практически не влияет на взаимодействие пользователя с нашим продуктом.

Лицензия выписывается отдельно для каждого из компонентов:

• Мобильные SDK для iOS и Android,

• Web SDK (адаптер и плагин),

• Oz BIO, который используется для серверных анализов при локальной установке.

Таким образом, если вы используете все три компонента нашего ПО, у вас будут три лицензии, каждая из которых будет привязана к своему компоненту.

Мобильные SDK (iOS и Android)

Для выпуска лицензии на мобильные (нативные) SDK нам потребуется bundle (application) ID вашего приложения. Лицензия бывает двух видов: онлайн и офлайн. Любой из этих типов работает с любым режимом анализа: на устройстве, на сервере или гибридным.

Онлайн-лицензия

Для онлайн-лицензии необходимо стабильное подключение к интернету. Такая лицензия в зависимости от условий вашего договора может иметь ограничения по количеству транзакций или устройств.

• Счетчик транзакций увеличивается на 1 при каждом запуске съемки видео для анализа.

• Счетчик устройств увеличивается на 1 при каждой установке нашего SDK на новое устройство.

При запуске SDK обращается к серверу лицензий и получает от него список параметров, в том числе показания счетчиков транзакций и устройств.

Основные преимущества онлайн-лицензии:

• Не нужно перевыпускать приложение после обновления лицензии,

• Не нужно перевыпускать приложение, если вы хотите добавить в лицензию новый bundle (application) ID. Все делается на лету.

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

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

Офлайн-лицензия

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

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

Как добавить лицензию в SDK:

Web SDK

Лицензия для Web SDK аналогична офлайн-лицензии для iOS и Android. Она работает и без интернета, все параметры прописаны в самом файле лицензии, нет ограничений по транзакциям или устройствам.

Разница между офлайн-лицензией для мобильных SDK и лицензией для Web SDK – только в том, что при продлении лицензии для Web SDK приложение перевыпускать не нужно.

Локальная установка (Oz BIO, серверная лицензия)

Пробная лицензия

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

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

В этом разделе собраны инструкции по интеграции серверных проверок Liveness.

Oz API – это API для распознавания лиц: как для проверки Liveness, так и для биометрической проверки, то есть сравнения лиц между собой.

Ключевые преимущества Oz API:

• Сохранение данных – ваши медиафайлы и анализы хранятся для будущего использования, пока вы самостоятельно их не удалите

• Возможность работать и с фото, и с видео

• Асинхронность анализов

• Безопасная аутентификация

• Гибкая настройка уровней доступа

Основная сущность в Oz API – это папка: в папку вы можете загружать медиафайлы, запускать для них анализы и получать результаты не только для отдельных анализов, но и для папки в целом.

Здесь мы приводим пошаговую инструкцию по проведению проверки Liveness для фото или видео лица, которое вы уже сняли с помощью бэкенда Oz.

• Создание папки

• Загрузка медиафайла в папку

• Проверка Liveness

• Получение результатов

Для вашего удобства и повышения точности анализов мы рекомендуем использовать для съемки медиа наши Web или Mobile SDK. Как это сделать, описано здесь:

Чтобы начать, вам понадобятся логин и пароль. Напишите нам, и вы отправим вам всю необходимую информацию, включая ссылки:

Логин: ivan_ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web Console: https://sandbox.ohio.ozforensics.com

1. Получите токен доступа

В ответе вам придет токен доступа. В дальнейшем его нужно будет указывать в поле X-Forensic-Access-Token.

2. Поместите отдельные фотографии в архивы (для версии 4.0.8 и ниже)

Внимание: если вы используете API версии 5.0.0 или новее, пропустите этот шаг.

3. Загрузите медиафайлы в папку

В поле payload укажите следующие теги:

В случае успеха вернется код 201. В ответе будет идентификатор папки folder_id – он понадобится в дальнейшем.

4. Запустите анализ

Метод вернет analyse_id, который потребуется на следующем шаге.

5. Запустите опрос для получения результатов

• качественные – в resolution (SUCCESS или DECLINED).

• количественные – в results_media[0].results_data.confidence_spoofing. confidence_spoofing; они варьируются от 0.0 до 1.0, где 0.0 означает, что на фото или видео реальный человек, а 1.0 – что система обнаружила спуфинг-атаку.

Коллекция Postman для описанных в статье шагов:

Из этой статьи вы узнаете, как интегрировать Oz Liveness Mobile SDK в клиентское мобильное приложение: для съемки видео с лицом и дальнейшей его проверки на сервере.

Oz Liveness Mobile SDK – это:

• Готовый интерфейс для съемки видео, который легко встроить в приложение клиента.

• Высокое качество видео, которое обеспечивает точность проверки Liveness.

«Под капотом» Oz SDK взаимодействует с OZ API.

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

Логин: ivan.ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web-консоль: https://sandbox.ohio.ozforensics.com

Мы также рекомендуем использовать наш сервис логирования – телеметрию. Записи телеметрии помогают в расследовании деталей атак. Для пользователей Oz API логирование подключается автоматически. Для локальных установок мы предоставим вам необходимые учетные данные.

Android

1. Добавьте SDK в проект

В build.gradle проекта добавьте строки:

В build.gradle модуля добавьте строки:

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в папку res/raw в вашем проекте.

3. Подключите SDK к Oz API

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

4. Add face recording

Для начала съемки используйте метод startActivityForResult:

Для получения готового видео используйте onActivityResult:

Готовые видео содержатся в объекте sdkMediaResult.

5. Запустите анализы

Для запуска анализов используйте код ниже. mediaList – массив объектов, полученных из sdkMediaResult или извне (если вы снимали видео без использования нашего SDK).

iOS

1. Добавьте SDK в проект

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в проект.

3. Подключите SDK к Oz API

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

4. Запустите съемку видео

Создайте контроллер, который будет снимать видео:

В делегате используйте протокол OZLivenessDelegate:

5. Запустите анализы

Для запуска анализов используйте AnalysisRequestBuilder. Метод run «под капотом» обратится к Oz API.

В руководстве разработчика вы также найдете инструкции по настройке внешнего вида SDK и список методов SDK как для iOS, так и для Android:

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

Из этой статьи вы узнаете, как интегрировать Oz Liveness Mobile SDK в клиентское мобильное приложение: для съемки видео с лицом и дальнейшей его проверки на устройстве без отправки данных на сервер.

Oz Liveness Mobile SDK – это:

• Готовый интерфейс для съемки видео, который легко встроить в приложение клиента.

• Высокое качество видео, которое обеспечивает точность проверки Liveness.

Android

1. Добавьте SDK в проект

В build.gradle проекта добавьте строки:

allprojects {
    repositories {
        maven { url "https://ozforensics.jfrog.io/artifactory/main" }
    }
}

В build.gradle модуля добавьте строки

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // номер версии можно найти в журнале изменений для Android
}

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в папку res/raw в вашем проекте.

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics))
)

OzLivenessSDK.INSTANCE.init(
        context,
        Collections.singletonList(new LicenseSource.LicenseAssetId(R.raw.forensics)),
        null
);

3. Запустите съемку видео

Для начала съемки используйте метод startActivityForResult:

val OZ_LIVENESS_REQUEST_CODE = 1
val intent = OzLivenessSDK.createStartIntent(listOf( OzAction.Blank)) startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE)

int OZ_LIVENESS_REQUEST_CODE = 1;
Intent intent = OzLivenessSDK.INSTANCE.createStartIntent(Collections.singletonList(OzAction.Blank));
startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE);

Для получения готового видео используйте метод onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
            val sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
            val sdkErrorString = OzLivenessSDK.getErrorFromIntent(data)
            if (!sdkMediaResult.isNullOrEmpty()) {
                analyzeMedia(sdkMediaResult)
            } else println(sdkErrorString)
        }
    }

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
        List<OzAbstractMedia> sdkMediaResult = OzLivenessSDK.INSTANCE.getResultFromIntent(data);
        String sdkErrorString = OzLivenessSDK.INSTANCE.getErrorFromIntent(data);
        if (sdkMediaResult != null && !sdkMediaResult.isEmpty()) {
            analyzeMedia(sdkMediaResult);
        } else System.out.println(sdkErrorString);
    }
}

Готовые видео содержатся в объекте sdkMediaResult.

4. Запустите анализы

Для запуска анализов используйте код ниже. mediaList – массив объектов, полученных из sdkMediaResult или извне (если вы снимали видео без использования нашего SDK).

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaList))
        .build()
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                result.forEach { 
                    println(it.resolution.name)
                    println(it.folderId)
                }
            }
            override fun onError(error: OzException) {
                error.printStackTrace()
            }
        })
} 

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaList, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    for (OzAnalysisResult result: list) {
                        System.out.println(result.getResolution().name());
                        System.out.println(result.getFolderId());
                    }
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

iOS

1. Добавьте SDK в проект

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => '<version>' // You can find the version needed in  iOS changelog

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в проект.

OZSDK(licenseSources: [.licenseFileName("forensics.license")]) { licenseData, error in
    if let error = error {
        print(error.errorDescription)
    }
}

3. Запустите съемку видео

Создайте контроллер, который будет снимать видео:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

В делегате используйте протокол OZLivenessDelegate:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

4. Запустите анализы

Для запуска анализов используйте AnalysisRequestBuilder.

let analysisRequest = AnalysisRequestBuilder()
let analysis = Analysis.init(
media: mediaToAnalyze, 
type: .quality, 
mode: .onDevice)
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
analysisRequest.run(
scenarioStateHandler: { state in }, // обработчик шагов сценария
uploadProgressHandler: { (progress) in } // обработчик загрузки файлов
) { (analysisResults : [OzAnalysisResult], error) in 
    // получение и обработка результатов анализов
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

Шаги выше помогут вам в базовой интеграции наших мобильных SDK в ваше приложение. Данные анализов, выполненных в режиме «на устройстве» никуда не отправляются, поэтому, в отличие от данных серверных проверок, они не будут доступны через API или в веб-консоли. Однако обратите внимание: для проверки лицензии потребуется подключение к интернету. Мы также рекомендуем использовать наш сервис логирования – телеметрию. Записи телеметрии помогают в расследовании деталей атак. Необходимые учетные данные мы предоставим.

В этом разделе описаны API- и SDK-компоненты биометрической системы Oz Forensics. API – бэкенд, компонент, отвечающий за взаимодействие всех модулей системы. SDK – «внешняя часть», с помощью которой:

1) ведется съемка видеороликов или изображений, которые затем обрабатываются API,

2) демонстрируется результат обработки.

У нашего API существует две версии, использоваться можно любую в зависимости от ваших потребностей.

Полная версия соответствует полнофункциональному API.

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

Мы также предоставляем SDK для вебсайтов и мобильных устройств.

Web SDK – модуль съемки и отправки медиаданных на анализы из веб-браузера. Он состоит из встраиваемого плагина и адаптера к этому плагину.

SDK для мобильных устройств включает в себя версии для iOs и Android.

Liveness – проверка «живости», того, что человек, снятый на видео, действительно живой реальный человек в сознании.

Биометрия – сравнение двух или более лиц с различных фотографий или видеороликов с целью ценить степень их схожести (один и тот же это человек или разные люди).

Лучший кадр – выбор лучшего кадра из видеоролика для использования его в бизнес-процессах как результата Liveness-проверки, «видео в виде картинки».

Проверка по ЧС (черному списку) – проверка, присутствует ли человек, чье фото или видео загружается в систему, в базе заранее загруженных фотографий.

Результаты анализов – получение результатов анализов через API в численной форме.

Из этой статьи вы узнаете, как интегрировать Oz Liveness Web SDK в клиентское Web-приложение: для съемки видео с лицом и дальнейшей его проверки на сервере.

Преимущества Oz Liveness Web SDK:

• Готовый интерфейс для съемки видео, который легко встроить в приложение клиента.

• Высокое качество видео, которое обеспечивает точность проверки Liveness.

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

• Возможность использования как SaaS-модели, так и локальной установки – с теми же функциями, но без необходимости слать какие-либо данные в облако.

«Под капотом» Web SDK взаимодействует с OZ API.

Мы рекомендуем начать с SaaS-модели и затем перейти к локальной установке – чтобы настроить бесшовную интеграцию Web SDK с вашими фронтендом и бэкендом. В этой инструкции приводятся шаги, благодаря которым процесс интеграции будет простым и ясным.

1. Получите доступ к персональной копии Web Adapter

Передайте нам информацию о доменных именах тех страниц, откуда планируется вызывать Web SDK, а также адрес электронной почты для создания аккаунта администратора. Пример:

Доменные имена:

1. www.yourbrand.com

2. www.yourbrand2.com

Электронная почта:

• ivan.ivanov@yourcompany.com

Мы направим вам ссылки и логин с паролем для дальнейшей интеграции и использования Web SDK.

Логин: ivan.ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web-консоль: https://sandbox.ohio.ozforensics.com

Web Adapter: https://web-sdk.cdn.sandbox.ozforensics.com/your_company_name/

1. Добавьте Web Plugin на вашу страницу

В HTML-коде страницы разместите следующее. web-adapter-url необходимо заменить на полученную от нас ссылку.

1. Реализуйте собственную логику для использования Web Plugin

Добавьте код, который будет запускать плагин и обрабатывать результаты:

• Настройка внешнего вида плагина

• Добавление дополнительного языка

• Настройка поведения плагина

• Настройка параметров и коллбэк-функций

• Рекомендации по безопасности

Для Angular и React нужно заменить https://web-sdk.sandbox.ohio.ozforensics.com в index.html.

В этом разделе находится инструкция по интеграции проверки Liveness на устройстве.

Файлы должны быть добавлены в теле запроса, теги – в поле payload.

Пример заполнения payload для пассивного Liveness и фотографии лицевой стороны документа:

Пример использования (Postman):

В случае успеха в ответе вернется информация о папке.

Алгоритм определения живости предназначен для проверки наличия живого человека по короткому видео фрагменту.

Порядок действий:

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ]
  }
}

{
  "analyses": [{
    "type": "quality",
    "source_media": ["6187a4ef-62c4-4445-bbb2-bf62d61f1fde"],
  }]
}

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

Сохраните analyse_id из ответа.

Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

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

Аутентификация пользователя

Чтобы получить токены доступа, нужно выполнить POST-запрос на /authorize/auth/. В теле запроса нужно указать полученные от нас электронную почту и пароль в составе credentials, а также API-адрес в качестве адреса хоста.

Body

{
	"credentials": {
		"email": "{{user_email}}",
		"password": "{{user_password}}"
	}
}

Результатом аутентификации пользователя является пара access_token и expire_token.

access_token – ключ (набор символов), предъявление которого является пропуском к ресурсам системы. Обращение к ним происходит с указанием в заголовках полученного access_token.

headers = {‘ X-Forensic-Access-Token’: <access_token>}

• для сервисных учетных записей – OZ_SESSION_LONGLIVE_TTL (по умолчанию 5 лет),

• для всех остальных – OZ_SESSION_TTL (по умолчанию 15 минут).

expire_token предназначен для обновления пары access_token и expire_token.

Автопродление сессий

если expire_date > текущей даты, то expire_date сессии устанавливается в значение текущей даты + временная дельта настроек, описанных выше.

Обновление токенов

Чтобы обновить пару access_token и expire_token, нужно выполнить POST-запрос на адрес authorize/refresh/ c expire_token в теле запроса и X-Forensic-Access-Token в заголовках.

{
    "expire_token": "{{expire_token}}"
}

Положительным результатом будет ответ с новой парой access_token и expire_token. Предыдущая пара access_token и expire_token будет удалена из базы данных при первой аутентификации по новой паре access_token и expire_token.

Возможные ошибки

В этом разделе вы найдете описание API.

Порядок действий:

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ]
  }
}

{
  "analyses": [{
    "type": "quality",
    "source_media": ["6187a4ef-62c4-4445-bbb2-bf62d61f1fde"],
    "params" : {
      "extract_best_shot": true
    }
  }]
}

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

Сохраните analyse_id из ответа.

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

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

5. Лучший кадр можно получить из ответа results_media -> output_images -> original_url

Результат любого анализа представляет собой число. Для анализа Biometry это число отражает степень совпадения/несовпадения лиц в загруженных вами медиафайлах по сравнению с референсами – теми файлами, которые хранятся в базе. Для анализа Liveness – возможность того, что на загруженном медиафайле не реальный живой человек в сознании, а какое-то его изображение или deepfake. Результаты анализов можно узнать и без захода в каждую заявку по отдельности – API предоставляет возможность извлечь их из JSON-ответа.

3. Для типа анализа Biometry ищите значение параметра min_confidence:

"items": 
 [
  {
   "analyses": 
    [
     {
      "analyse_id": "biometry_analysis_id"
      "folder_id": "some_folder_id", 
      "type": "BIOMETRY", 
      "state": "FINISHED", 
      "results_data": 
       {
        "max_confidence": 0.997926354, 
        "min_confidence": 0.997926354
       }

Этот параметр отражает уверенность системы в том, что на представленных медиа фигурирует один и тот же человек.

4. Для типа анализа Liveness Analysis ищите значение параметра confidence_spoofing для нужного медиафайла:

"items": 
 [
  {
   "analyses": 
    [
     {
      "source_media": 
       [
        {
        "media_id": "your_media_id", 
        "media_type": "VIDEO_FOLDER",
        }
       ]
      "results_media": 
       [
        "analyse_id": "liveness_analysis_id",
        "results_data": 
         {
          "confidence_spoofing": 0.55790174
         }

Этот параметр показывает вероятность спуфинг-атаки – того, что на полученном видео, например, использовалась технология deepfake или вместо человека программе показали видеоролик с этим человеком.

Если нужно обработать несколько результатов анализов, запросите список заявок и сделайте парсинг JSON-ответа.

CocoaPods

Для добавления OZLivenessSDK в ваше приложение через менеджер зависимостей CocoaPods и интеграции OZLivenessSDK в проект Xcode добавьте в Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => 'VERSION'

Начиная с версии 8.1.0, можно использовать упрощенный код:

// для установки последней версии
pod ‘OZLivenessSDK’
// ИЛИ для установки конкретной версии
// pod ‘OZLivenessSDK’, ‘8.10.0’

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

pod 'OZLivenessSDK/Core', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios.git',  :tag => 'VERSION'

Для версий 8.1.0 и выше:

pod ‘OZLivenessSDK/Core’
// ИЛИ
// pod ‘OZLivenessSDK/Core’, ‘8.1.0’

SPM

Установка через SPM возможна для SDK версий 8.7.0 и новее.

Ручная установка

Вы также можете добавить файлы SDK в проект вручную.

• OZLivenessSDK.xcframework,

• OZLivenessSDKResources.bundle,

• OZLivenessSDKOnDeviceResources.bundle (если вы не используете анализы на устройстве, этот файл можно не скачивать).

2. Убедитесь, что:

• оба файла xcframework отображаются в Target-Build Phases -> Link Binary With Libraries и Target-General -> Frameworks, Libraries, and Embedded Context;

• файл(ы) bundle отображаются в Target-Build Phases -> Copy Bundle Resources.

Коллекция в Oz API – это база фотографий лиц (персон), которые используются в анализе Blacklist для сравнения с лицом человека с только что снятого фото или видео.

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

Как создать коллекцию

Коллекция создается в рамках определенной компании, таким образом, для добавления новой коллекции необходим идентификатор компании company_id.

Если вы его не знаете, найдите компанию поиском с помощью метода GET /api/companies/?search_text=test, где test – наименование компании или его часть. Сохраните полученный company_id.

Для создания коллекции вызовите метод POST /api/collections/. В теле запроса укажите название своей коллекции (alias) и company_id нужной компании, как показано ниже:

{
  "alias": "blacklist",
  "company_id": "your_company_id"
}

В ответе на запрос будет идентификатор коллекции collection_id. Он понадобится на следующем шаге.

Как добавить персону или фото в коллекцию

{
    "media:tags": {
        "image1": [
            "photo_selfie",
            "orientation_portrait"
        ]
    }
}

В ответе вам придет идентификатор персоны person_id - это идентификатор отдельного человека в коллекции.

В этом же запросе через payload можно добавить данные о персоне:

    "person:meta_data": {
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },

Вы также можете загрузить дополнительные фото персоны после ее добавления: используйте метод POST {{host}}/api/collections/{{collection_id}}/persons/{{person_id}}/images/ с соответствующим person_id. Тело запроса заполните так же, как для метода POST /api/collections/{{collection_id}}/persons/.

Чтобы получить информацию о всех персонах в коллекции, вызовите метод GET /api/collections/{{collection_id}}/persons/.

Если вам нужен список фотографий для отдельной персоны, воспользуйтесь методом GET /api/collections/{{collection_id}}/persons/{{person_id}}/images/. Обратите внимание: для каждого фото будет указан идентификатор фото person_image_id – он потребуется вам, например, для удаления фото.

Как удалить фото или персону из коллекции

Чтобы удалить персону со всеми соответствующими ей фотографиями, используйте метод DELETE /api/collections/{{collection_id}}/persons/{{person_id}}, указав идентификаторы коллекции и персоны. Все фото этой персоны удалятся автоматически. Персону нельзя удалить, если с ней связаны анализы – то есть если эта персона участвовала в анализе Black list и с ней были найдены совпадения. Для удаления такой персоны сперва нужно удалить соответствующие анализы методом DELETE /api/analyses/{{analyse_id}} (потребуется analyse_id анализа collection (Black list)).

Для удаления всех связанных с коллекцией анализов запросите список всех папок с анализом Black list: call GET /api/folders/?analyse.type=COLLECTION. Для каждой папки из списка (GET /api/folders/{{folder_id}}/), найдите analyse_id нужного анализа, а затем удалите анализ – DELETE /api/analyses/{{analyse_id}}.

Для удаления определенной фотографии той или иной персоны вызовите метод DELETE /api/collections/{{collection_id}}/persons/{{person_id}}/images/{{person_image_id}} и укажите идентификаторы коллекции, персоны, фотографии.

Как удалить коллекцию целиком

Перед удалением коллекции нужно удалить информацию о всех входящих в нее персонах, а затем стереть саму коллекцию с помощью метода DELETE /api/collections/{{collection_id}}/.

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

Порядок действий:

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ],
    "photo1": [
      "photo_selfie"
    ],
    "doc1": [
      "photo_id",
      "photo_id_front"
    ]
  }
}

{
  "analyses": [{
    "type": "biometry",
  }]
}

Не указывайте source_media, если хотите провести анализ всех медиа в папке в соответствии с установленными им тегам.

Сохраните analyse_id из ответа.

Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

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

Иерархия объектов

Объекты системы имеют иерархическую структуру подчинения.

1. На верхнем уровне находится Компания. Это значит, что один экземпляр установки Oz API может обслуживать пользователей нескольких не зависящих друг от друга компаний.

Поля объектов

Каждый объект имеет набор полей для работы и идентификации на уровне REST API запросов.

Общие поля

Объект Компания

Объект Пользователь

Объект Папка

Объект Медиа

Объект Анализ

В Oz Api существует несколько видов анализов:

Biometry

Назначение

Результат

Анализ выдает уровень схожести изображений лиц в процентах от 100 до 0% (1->0), где:

• 100% (1) – максимальная схожесть,

• 0% (0) – схожесть отсутствует.

Quality (Liveness, Best Shot)

Назначение

Алгоритм определения живости Liveness (анализ Quality) предназначен для проверки наличия живого человека в коротком видеоролике или на фото.

Результат

Анализ выдает возможность спуфинга*/атаки в процентах, где:

• 100% (1) – атака, перед камерой не живой человек,

• 0% (0) – перед камерой реальный человек в сознании.

*Спуфинг в биометрической области – (англ. spoofing – подмена) это ситуация, в которой человек маскируется под другого человека, используя программные и не программные средства (виртуальная камера, демонстрация изображения лица с экрана смартфона или фотографии, маски или силиконовой головы).

Documents

Назначение

Анализ распознавания и проверки документов предназначен для базового определения наличия документа в кадре и проверки корректности полей документа согласно его типу. Параллельно проводится биометрический анализ (сверка фотографии из документа и селфи, сделанного человеком).

Результат

Анализ документов выдает два варианта результатов:

• Документы успешно проверены,

• Документы не прошли проверку.

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

Blacklist

Назначение

Алгоритм проверки по черному списку предназначен для проверки присутствия человека в базе заранее загруженных фото.

База заранее загруженных фото может называться как "Черным списком", если туда внесены фотографии лиц мошенников или других нежелательных для бизнеса людей, так и "Белым списком", если она содержит фотографии лиц VIP-персон.

Результат

Анализ по черному списку выдает процент схожести от 100 до 0% (1->0), где:

• 100% (1) – это максимальная схожесть, алгоритм нашел совпадения с изображениями из черного списка.

• 0% (0) – минимальная схожесть, алгоритм не нашел совпадений с изображениями из черного списка.

Теги видеофайлов

Для видеофайлов в Системе должны быть указаны следующие типы тегов:

• Тег, определяющий тип данных «видео»:

  • video_selfie

• Тег, определяющий ориентацию видео:

  • orientation_portrait – портретная ориентация;

  • orientation_landscape – ландшафтная ориентация.

• Тег, определяющий действие на видео:

  • video_selfie_left – поворот головы налево;

  • video_selfie_right – поворот головы направо;

  • video_selfie_down – наклон головы вниз;

  • video_selfie_high – наклон головы вверх;

  • video_selfie_smile – улыбка;

  • video_selfie_eyes – моргание;

  • video_selfie_scan – сканирование;

  • video_selfie_oneshot – анализ по одному кадру;

  • video_selfie_blank – нет действия.

Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Пример корректного набора тегов видеофайла с действием «моргание»:

  "video1": [
      "video_selfie",
      "video_selfie_eyes",
      "orientation_portrait"
    ]

Теги фотофайлов

Для фотофайлов в Системе должны быть указаны следующие типы тегов:

• Тег для селфи:

  • photo_selfie – тег, определяющий тип фотографии «селфи»

• Теги для фотографий или сканов удостоверений личности:

  • photo_id – тег, определяющий тип фотографии «документы»;

  • photo_id_front – фото лицевой стороны документа;

  • photo_id_back – фото обратной стороны документа (любые другие анализы, кроме Документов, файлы с этим тегом игнорируют).

Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Пример корректного набора тегов фотофайла «селфи»:

  "photo1": [
      "photo_selfie"
  ]

Пример корректного набора тегов фотофайла с лицевой стороной документа:

"photo1": [
    "photo_id", "photo_id_front"
]

Пример корректного набора тегов фотофайла с обратной стороной документа:

"photo1": [
    "photo_id", "photo_id_back"
]

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

Внимание: в версии API 4.0.8 и ниже, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Анализ выполняется для всех фото и видео.

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

Анализ выполняется только при наличии заранее созданного черного списка для всех присутствующих в папке / указанных в качестве источника фото и видео.

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

Documents

Сверка лица с документами (анализ “Documents”) выполняется для медиафайлов с тегами photo_id_front, photo_id_back (документы) и photo_selfie (селфи). Результат сверки будет положительным, если есть фото лица и хотя бы один валидный документ (с фотографией того же лица) из списка ниже:

• паспорт

• водительские права

• заграничный паспорт

Связанные с тегами ошибки

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

Каждая роль комбинируется с флагами is_admin и is_service и в зависимости от них может менять поведение.

Флаг is_service предназначен для создания сервисных пользователей учётных записей для входа автоматизированным способом. При авторизации под таким пользователем выдаётся токен с долгим временем жизни (по умолчанию 5 лет). Время жизни токенов для обычных пользователей составляет 15 минут (параметризуется), по умолчанию время жизни токенов продлевается при каждом обращении (параметризуется).

• ADMIN – Администратор системы. Имеет неограниченный доступ ко всем ресурсам системы через API, кроме принятия решений по анализам;

• CLIENT – Клиентская учетная запись. В рамках своей компании имеет доступ к загрузке медиафайлов, запуску анализов, просмотру результатов в своих папках, выгрузке отчетности по заявке;

  • is_admin – если установлен, пользователь получает доступ к данным всех пользователей внутри своей компании

  • can_start_analyse_biometry – дополнительный флаг для ограничения доступа к проведению биометрии (по умолчанию разрешено)

  • can_start_analyse_quality – дополнительный флаг для ограничения доступа к проведению анализов Liveness (по умолчанию разрешено)

• CLIENT ADMIN – администратор компании, который может управлять пользователями и аккаунтом своей компании. CLIENT ADMIN может просматривать данные всех пользователей и редактировать их, просматривать статистику, удалять файлы в папках, шаблоны отчетов вместе с вложениями, сами отчеты и отдельные анализы, а также может добавлять шаблоны отчетов и изображения в ЧС. Роль есть только в Web UI, вне Web UI она заменяется на роль CLIENT c флагом is_admin = true.

• CLIENT OPERATOR – имеет такие же права, как и OPERATOR, но в рамках своей компании.

Подробное описание уровней доступа приведено ниже.

Компания

Папка

Шаблон отчета

Приложения к шаблону отчета

Отчет

Анализ

Коллекция

Персона

Фото персоны

Пользователь

Обзор

Объекты и методы

Метаданные можно добавить к большинству объектов системы. Список объектов с соответствующими им методами для добавления метаданных приведен ниже. Также метаданные можно указать при создании объекта.

Примеры использования

Метаданные могут вам потребоваться, например, если вы захотите группировать папки (заявки) по людям или лидам. Например, для подсчета конверсии в случаях, когда один лид делает несколько попыток пройти анализ Liveness, добавьте идентификатор этого лида в метаданные соответствующих папок.

Чтобы добавить идентификатор клиента iin к объекту папки, в тело запроса внесите соответствующую запись:

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

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

Загрузите JSON-файл с нужной коллекцией Postman:

Коллекция Oz API

5.3 и 5.2

5.0

Oz API 5.1.0 работает с этой же коллекцией.

4.0

3.33

Импорт коллекции Postman

После запуска клиента необходимо импортировать актуальную коллекцию для Postman, для этого в клиенте нажмите кнопку Import:

Нажмите files для выбора файла, найдите нужный JSON и нажмите Открыть:

Импортированная коллекция со всеми методами взаимодействия появится в интерфейсе Postman:

Ниже приведены разъяснения по каждому статусу.

Состояние анализа (analyse.state)

Состояние выполнения анализа принимает следующие значения:

PROCESSING – в обработке;

FAILED – анализ выполнить не удалось, произошла ошибка;

FINISHED – выполнение анализа завершено.

Результат анализа (analyse.resolution_status)

Если выполнение анализа завершено, результат выполнения может принимать следующие значения:

SUCCESS– проверка пройдена успешно;

DECLINED – проверка не пройдена (лицо не совпало или совпало с лицом из ЧС в зависимости от настроек, атака, лицо не совпало с лицом в документах).

Если анализ не завершен, результат наследует значение из analyse.state: PROCESSING (еще в обработке) / FAILED (возникли ошибки, завершить анализ не удалось).

Состояние заявки (folder.resolution_status)

Заявка – это папка, в которой лежат медиафайлы для анализа. Если анализы еще не завершены, в resolution_status вы увидите одно из следующих значений:

INITIAL – анализы не назначены;

PROCESSING – анализы выполняются;

FAILED – выполнить анализы не удалось (произошли ошибки);

FINISHED – папка обработана, выполнение анализов завершено.

Результат заявки (system_resolution)

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

SUCCESS– все хорошо, проверки пройдены успешно;

OPERATOR_REQUIRED (кроме анализа Liveness) – анализы со статусом DECLINED отсутствуют, но один или больше анализов завершились со статусом OPERATOR_REQUIRED;

DECLINED – один или больше анализов завершились с результатом DECLINED, то есть проверка не прошла.

Отличия архитектуры Lite от типовой

• Только один компонент, который нужно кластеризовать.

• Нет хранилища данных – более высокий уровень защиты информации.

• Более простая архитектура – более короткие сроки реализации проекта.

Примеры методов

5.3.1 – 24.12.2024

• Оптимизировали потребление серверных ресурсов при проведении биометрического анализа.

5.3.0 – 21.11.2024

• Подготовили новый шаблон отчета, который также соответствует этим требованиям.

• Миниатюры для нового отчета генерируются на основе кадров с действиями.

5.2.0 – 06.09.2024

• Добавили метод проверки настроек таймзоны: GET {{host}}/api/config

• Добавили параметры к методу GET {{host}}/api/event_sessions:

  • time_created

  • time_created.min

  • time_created.max

  • time_updated

  • time_updated.min

  • time_updated.max

  • session_id

  • session_id.exclude

  • sorting

  • offset

  • limit

  • total_omit

• При создании папки с SHOT_SET соответствующее видео будет в media.video_url.

• Исправили ошибку, из-за которой CLIENT ADMIN не мог установить новый пароль для пользователя из своей компании.

5.1.1 – 16.07.2024

• Обновления безопасности.

5.1.0 – 20.03.2024

• Добавили возможность сравнения лица с большой базой фотографий, содержащей миллион фото и более, – Face Identification 1:N.

• Анализ Liveness (QUALITY) теперь игнорирует фото с тегами photo_id, photo_id_front или photo_id_back.

5.0.1 – 16.07.2024

• Обновления безопасности.

5.0.0 – 17.11.2023

• Анализ Liveness (QUALITY) теперь работает и с изображениями.

• Исправили ошибку, из-за которой анализ Liveness мог завершиться с успехом при отсутствии медиафайлов в папке (заявке).

• Для extract_best_shot изменили значение по умолчанию на True.

• Архивы RAR больше не поддерживаются.

• По умолчанию в analyses.results_media.results_data теперь один параметр: confidence_spoofing. Если для обратной совместимости нужны все три (confidence_replay, confidence_liveness и confidence_spoofing), это можно настроить.

• Обновили PDF-отчет, который грузится по умолчанию.

• Название PDF-отчета теперь содержит folder_id.

4.0.8-patch1 – 16.07.2024

• Обновления безопасности.

4.0.8 – 22.05.2023

• Настроили авторотацию логов.

• Добавили консольную команду для удаления пользователя.

• Генерацию предпросмотра видео теперь можно отключить.

• Токен доступа для роли ADMIN теперь действителен 5 лет.

• Добавили идентификатор папки folder_id к названию отчета.

• Исправили ошибки и оптимизировали работу API.

4.0.2 – 13.09.2022

• Система теперь удаляет ненужные кадры, оставшиеся после раскадровки видео.

• Добавили новые методы GET and POST для media/<media_id>/snapshot/

• Заменили шаблон отчета по умолчанию.

• Превью для набора кадров теперь показывается с исходным соотношением сторон.

• ADMIN и OPERATOR автоматически добавляются в system_company.

• Для User, Folder, Analyse, Media добавили атрибут company_id.

• Для Analysis добавили атрибут group_id.

• Для Folder и Analysis добавили атрибут system_resolution.

• resolution_status теперь возвращает значение system_resolution.

• Убрали метод PATCH для коллекций.

• Добавили фильтр по resolution_status для Folder Analyses [LIST] и по analyse.resolution_status для Folder [LIST].

• Для Folder, User, Company добавили журналирование.

• Обновили алгоритм удаления компании.

• Улучшили логику обработки черных списков.

• Исправили несколько багов.

3.33.0

• Модули Photo Expert и KYC удалены.

• Обновили конечную точку для изменения пароля пользователя: POST users/user_id/change-password вместо PATCH.

3.32.1

• Доступен лог для Celery.

3.32.0

• Добавили в параметры запроса Folder [LIST] фильтры: analyse.time_created, analyse.results_data для анализа Documents, results_data для анализа Biometry, results_media_results_data для анализа QUALITY. Для включения фильтра установите True в параметре запроса with_results_media_filter.

3.31.0

• Добавили новый атрибут для пользователей – is_active (по умолчанию True). Если выставлено False, пользователь не может совершать никакие действия.

• Добавили новую ошибку, которая выводится в ответ на попытку заблокированного пользователя что-либо сделать.

3.30.0

• Добавили превью наборов изображений.

• Теперь наборы можно сохранять на диск через атрибуты original_local_path, original_url.

• Добавили атрибут original_info для набора изображений – в нем хранятся сумма md5, размер, mime-тип.

• Исправили отчет для наборов изображений.

3.29.0

• Добавили “проверку здоровья” системы - метод GET api/healthcheck. Можно задать перечень имен / очередей задач на проверку активности.

3.28.1

• Поправили ссылку на миниатюру для набора изображений.

3.28.0

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

3.27.0

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

• Поменяли алгоритм вызова callbacks.

• Переработали и описали инструменты командной строки.

• Провели рефакторинг модулей.

3.25.0

• Поменяли подметод и метод для удаления персональных данных – с delete_pi на /pi и с POST на DELETE соответственно.

3.23.1

• Улучшили алгоритм удаления персональных данных.

• В папки, которые были очищены, теперь нельзя добавлять медиа.

3.23.0

• Поменяли название подметода авторизации с auth на auth_restore.

• Добавили тег video_selfie_oneshot.

• Добавили настройки валидации пароля.

• Добавили задержки для auth, rest_unauthorized, rps_with_token (OZ_THROTTLING_RATES в настройках, по умолчанию отключено).

• Теперь можно проверять доступы пользователя к статичным файлам (OZ_USE_PERMISSIONS_FOR_STATIC в настройках, по умолчанию – False).

• Добавили новый подметод для заявки - /delete_pi. С его помощью можно удалить в заявке все персональные данные и связанные с ними анализы.

3.22.2

• Добавили ошибку, которая появляется при попытке синхронизировать пустые коллекции.

3.22.0

• Добавили параметр fields_to_check к анализу документов (по умолчанию проверяет все поля).

• Добавили параметр double_page_spread к анализу документов (по умолчанию включен).

3.21.3

• Поправили синхронизацию коллекций.

3.21.0

• Теперь можно продлить токен авторизации с помощью expire_token.

3.20.1

• Добавили поддержку application/x-gzip.

3.20.0

• Переименовали shots_set.images в shots_set.frames.

3.18.0

• Добавили набор функций по управлению сессиями пользователя.

• Пользователи могут менять владельцев заявок (в соответствии со своими доступами).

• Поменяли правила зависимостей.

• Поправили баг с продлением авторизации.

3.16.0

• Переместили функционал синхронизации коллекций в oz_core.

3.15.3

• Упростили работу с наборами изображений. Один набор – один архив.

3.15.2

• Улучшено распознавание документов для Dockered-версии.

3.15.1

• Переместили проверку тега ориентации в анализ Quality.

3.15.0

• Добавили шаблон отчета по умолчанию для ролей Admin и Operator.

3.14.0

• Обновили биометрическую модель.

3.13.2

• Исправили ошибку с созданием объекта набора изображений без изображений.

• Добавили новый формат обмена данными для модуля распознавания документов.

3.13.1

• Если для персон в коллекции проводились какие-либо анализы, коллекцию теперь нельзя удалить.

3.13.0

• Добавили к анализам временные метки time_task_send_to_broker, time_task_received, time_task_finished.

3.12.0

• Добавили новый механизм авторизации – соединение с Active Directory через LDAP.

3.11.0

• Добавили новый тип медиа в заявку: "shots_set"

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

3.10.

• Переименовали поле заявки resolution_suggest в operator_status.

• Добавили к заявке текстовое поле operator_comment.

• Доступ на редактирование полей заявки operator_status и operator_comment есть у Admin, Operator, Client Service, Client Operator и Client Admin.

• Доступ на удаление заявки, медиа из заявки, шаблонов отчетов и их вложений, самих отчетов и анализов теперь есть только у Admin и Client Admin (в рамках компании).

3.9.0:

• Исправили удаление отчетов – теперь они удаляются при удалении их автора.

3.8.1

• Поправили доступы – Client теперь может просматривать только свой профиль.

3.8.0

• Client Operator теперь может редактировать только свой профиль.

• Client больше не может удалять свои заявки, любые медиа, отчеты или анализы.

• Client Service может создавать персон в коллекциях и просматривать отчеты в рамках компании.

3.7.1

• У ролей Client, Client Admin, Client Operator теперь есть доступы на просмотр профилей пользователя только внутри компании.

• Запустили альфа/бета-тестирование.

• Теперь поддерживаем заголовок с датой просрочки токена авторизации.

• Добавили поддержку модуля распознавания документов для стенделона и Docker.

3.7.0

• Добавили роль Client Operator – это Client Admin, но без доступа к управлению аккаунтом и компанией.

• И Client Admin, и Client Operator могут менять статус анализа.

• Создавать, редактировать и удалять что-либо в моделях Collection и CollectionPerson в рамках компании теперь могут только Admin и Client Admin.

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

• Поправили код статуса, который возвращается при создании коллекции, с 200 на 201.

Загрузите JSON-файл с коллекцией Postman:

1.2.0

1.1.1

Импорт коллекции Postman

После запуска клиента необходимо импортировать актуальную коллекцию для Postman, для этого в клиенте нажмите кнопку Import:

Нажмите files для выбора файла, найдите нужный JSON и нажмите Открыть:

Импортированная коллекция со всеми методами взаимодействия появится в интерфейсе Postman: