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

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

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

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

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

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

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

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

На Android при запуске анализа установите HYBRID в Mode. На iOS аналогично: hybrid в mode. Проще простого.

Если у вас остались вопросы, будем рады на них ответить.

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

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

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

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

Эти анализы доступны в Oz API как для модели SaaS, так и для локальной установки наших продуктов. Liveness и Face Matching также работают в режиме «на устройстве». Детальная информация по моделям использования находится здесь.

Liveness

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

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

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

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

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

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

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

Как интегрировать серверную проверку Liveness в ваше Web-приложение

Как интегрировать серверную проверку Liveness в ваше мобильное приложение

Как провести проверку медиафайла на Liveness без использования фронтенда Oz

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

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

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

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

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

Узнать о том, как внедрить технологию Face Matching в ваши процессы, вы можете в наших руководствах по интеграции.

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

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

Больше об типах анализов и о том, что они проверяют, вы можете прочитать здесь.

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

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

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

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

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

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

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

Пассивный Liveness

Активный Liveness

Чтобы определить наличие тех или иных действий из списка для активного и пассивного Liveness, наши алгоритмы полагаются на теги. Эти теги соответствуют действиям, производимым пользователем во время записи видео. Узнать о тегах больше вы можете здесь. Таблица соответствия действий (или, другими словами, жестов) для различных компонентов Oz Liveness находится здесь.

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, которые вы можете встроить в вашу инфраструктуру в различных сочетаниях – в зависимости от того, что вам требуется.

Самые распространенные сценарии интеграции описаны в разделе Краткие руководства по интеграции.

Oz API

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

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

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

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

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

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

Дополнительную информацию вы можете найти в статьях Ключевые понятия Oz API и Руководство разработчика: Oz API. Проверить, как работает Oz API, можно с помощью нашей коллекции Postman.

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

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

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

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

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

iOS и Android SDK

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

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

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

Анализ на сервере проводится либо с помощью соответствующих методов SDK, либо через Oz API – в этом случае вам нужно будет вызывать его методы из вашего мобильного приложения, либо опять же через Oz API, но уже с вашего бэкенда, куда предварительно передаются готовые видеоролики. Базовый сценарий интеграции описан здесь.

Анализ на устройстве (Liveness и Face matching) не требует взаимодействия с Oz API и даже подключения к интернету, он выполняется прямо на телефоне. Такой анализ применим при высоких требованиях к конфиденциальности, когда вы не хотите, чтобы какая-либо информация «ушла» с телефонов пользователей. Как работает такой анализ, описано здесь.

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 SDK описаны здесь, а в этом разделе вы можете ознакомиться с руководством разработчика.

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

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

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

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

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

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

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

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

Детальную информацию о модуле можно найти здесь.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда вы запускаете наши 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, серверная лицензия)

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

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

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

Из этой статьи вы узнаете, как интегрировать 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.

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

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

В целях безопасности каждый вызов Oz API требует наличия в заголовке токена доступа. Чтобы получить этот токен, вызовите метод POST /api/authorize/auth с полученными от нас логином и паролем. В ответе вы получите токен доступа. Его нужно будет указывать в заголовке X-Forensics-Access-Token во всех последующих вызовах методов Oz API. Подробнее процесс аутентификации описан .

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

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

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

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

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

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

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

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

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

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

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

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

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

Oz Liveness Mobile SDK – это:

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

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

Для работы Oz Liveness Mobile SDK нужна лицензия, которая привязывается к bundle_id приложения, например com.yourcompany.yourapp. Тестовую лицензию на месяц вы можете оформить самостоятельно на нашем веб-сайте, если вам требуется лицензия на более длительный срок – свяжитесь с нами.

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 в проект

Установите OZLivenessSDK через CocoaPods. Чтобы встроить SDK в проект Xcode, в Podfile добавьте:

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 или в веб-консоли. Однако обратите внимание: для проверки лицензии потребуется подключение к интернету. Мы также рекомендуем использовать наш сервис логирования – телеметрию. Записи телеметрии помогают в расследовании деталей атак. Необходимые учетные данные мы предоставим.

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

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

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

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

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

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

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

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

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

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

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

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

• Проверка Liveness

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

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

• Интеграция Oz Liveness Web SDK

• Интеграция Oz Liveness Mobile SDK

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

Логин: ivan_ivanov@yourcompany.com

Пароль: …

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

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

Со всеми методами Oz API можно ознакомиться здесь: коллекция Postman.

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

Мы рекомендуем использовать токен доступа вместо логина и пароля, так как это более безопасно. Вызовите метод POST /api/authorize/auth. В теле запроса укажите логин и пароль

{
    "credentials": {
        "email": "<login>", // электронная почта для доступа администратора
        "password": "<password>" // полученный от нас пароль
     }
}

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

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

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

В версии 4.0.8 и ниже проверка Oz Liveness может производиться либо по видео, либо по последовательности кадров в архиве. Таким образом, если вы хотите запустить проверку по одной фотографии, ее необходимо добавить в ZIP-архив. Oz API будет обрабатывать этот архив так же, как видео. Обратите внимание: теги к этому архиву необходимо указывать из списка тегов для видео.

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

Чтобы создать папку и добавить в нее ваши фото и видео, вызовите метод POST /api/folders/ и добавьте медиафайлы в тело запроса.

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

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

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

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

Для запуска анализа вызовите метод POST /api/folders/{{folder_id}}/analyses/ и укажите в нем folder_id из предыдущего шага. В теле запроса укажите анализ Liveness (Quality).

{
    "analyses": [
        {
            "type": "quality"
        }
    ]
}

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

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

Раз в секунду отправляйте запрос GET /api/analyses/{{analyse_id}} с полученным ранее analyse_id, пока состояние анализа не изменится с PROCESSING на какое-либо другое. Когда анализ завершится, вы сможете оценить результаты:

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

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

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

Шаги выше помогут вам выполнить Liveness-проверку через Oz API. Чтобы получить доступ к снятым видео и результатам анализов, воспользуйтесь веб-консолью или API-запросами.

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

Из этой статьи вы узнаете, как интегрировать 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 Liveness Mobile SDK нужна лицензия, которая привязывается к bundle_id приложения, например com.yourcompany.yourapp. Тестовую лицензию на месяц вы можете оформить самостоятельно на нашем веб-сайте, если вам требуется лицензия на более длительный срок – свяжитесь с нами.

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

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. Подключите SDK к Oz API

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

OzLivenessSDK.setApiConnection(
    OzConnection.fromCredentials(host, username, password),
    statusListener(
        { token -> /* token */ },
        { ex -> /* error */ }
    )
)

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromCredentials(host, username, password),
        new StatusListener<String>() {
            @Override
            public void onStatusChanged(@Nullable String s) {}
            @Override
            public void onSuccess(String token) { /* token */ }
            @Override
            public void onError(@NonNull OzException e) { /* error */ }
        }
);

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

OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(host, token))

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromServiceToken(host, token), 
        null
);

4. Add face recording

Для начала съемки используйте метод 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.

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

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

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, 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.SERVER_BASED, 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 в проект

Установите OZLivenessSDK через CocoaPods. Чтобы встроить SDK в проект Xcode, в Podfile добавьте:

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. Подключите SDK к Oz API

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

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Your code to handle error or token
}

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

OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://api.sandbox.ozforensics.com", token: token)) { (token, error) in
}

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

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

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)

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

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

let analysisRequest = AnalysisRequestBuilder()
let analysis = Analysis.init(
media: mediaToAnalyze, 
type: .quality, 
mode: .serverBased)
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-запросами.

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

В этой статье вы узнаете, как сравнить лицо из готового Liveness-видео с лицом на референтной фотографии, сохраненной в вашей базе данных.

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

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

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

1. Получите идентификатор папки, где находится нужное видео –folder_id

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

• Для видео, записанного через наши мобильные SDK, получите идентификатор папки из результатов анализа:

Android:

iOS:

2. Загрузите в папку референтное фото из своей базы данных

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

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

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

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

• количественные – в analyses.results_data.min_confidence

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

Пожалуйста, обратите внимание: в мобильных SDK Oz отсутствует интерфейс для съемки документов. Для этого вам потребуется ПО стороннего производителя или ваше собственное. В Web SDK возможность съемки документа есть.

Ниже описаны шаги, которые потребуется пройти для добавления сравнения лиц к Liveness-проверке.

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

Добавление съемки документа в Web SDK

Добавьте photo_id_front в список действий для плагина.

Добавление сравнения лиц в Android SDK

Внимание: в данном случае мы предполагаем, что фотография (например, документа) хранится на устройстве под названием reference.jpg.

Измените код, запускающий анализ:

Для анализа на устройстве вместо Analysis.Mode.SERVER_BASED укажите Analysis.Mode.ON_DEVICE.

Добавление сравнения лиц в iOS SDK

Внимание: в данном случае мы предполагаем, что фотография (например, документа) хранится на устройстве под названием reference.jpg.

Измените код, запускающий анализ:

Для анализа на устройстве вместо .serverBased укажите .onDevice.

Для всех SDK

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

Описание

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

• предоставляет единый Rest API для запуска Liveness и Biometry анализов

• ведет базу запросов и выполненных анализов

• архивирует входящие медиаданные

• собирает телеметрию с подключенных мобильных приложений

• предоставляет возможность настроить специфичные модели устройств

• генерирует подробные отчеты о результатах выполнения анализов

Описание основных методов Rest API схемы:

Коллекция Postman, включающая в себя все имеющиеся на данный момент методы:

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

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

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

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

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

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

Алгоритм "лучший кадр" выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу liveness.

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

1. Авторизуйтесь.

2. Поместите видеофайл в папку.

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

3. Запустите анализ. Убедитесь, что параметр "extract_best_shot" имеет значение True, как показано ниже.

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

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

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

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

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

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

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

Подробно статусы анализов описаны здесь.

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

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

Коллекция в 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. Он понадобится на следующем шаге.

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

Для добавления новой персоны в коллекцию вызовите метод POST /api/collections/{{collection_id}}/persons/, где collection_id – идентификатор коллекции из предыдущего шага. В запросе передайте фото персоны (или несколько фото). В Payload укажите соответствующие фото теги, как показано ниже.

{
    "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}}/.

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

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

1. Авторизуйтесь.

2. Поместите медиафайлы в папку.

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

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

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

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

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

4а. Через некоторое время проверьте результат.

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

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

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

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

Подробно статусы анализов описаны здесь.

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

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

1. Авторизуйтесь.

2. Поместите медиафайл в папку.

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

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

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

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

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

4а. Через некоторое время проверьте результат.

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

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

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

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

Подробно статусы анализов описаны здесь.

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

1. Авторизуйтесь.

2. Сделайте запрос к заявке или списку заявок. Параметр with_analyses должен быть установленTrue.

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-ответа.

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

• biometry,

• quality (liveness, best shot),

• documents,

• blacklist.

Biometry

Назначение

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

Результат

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

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

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

Quality (Liveness, Best Shot)

Назначение

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

Алгоритм "лучший кадр" (best shot) выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу liveness.

Результат

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

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

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

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

Documents

Назначение

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

Результат

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

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

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

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

Blacklist

Назначение

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

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

Результат

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

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

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

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

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

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

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

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

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

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

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

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

OPERATOR_REQUIRED (кроме анализа Liveness) – требуется оператор (т.е. дополнительная проверка человеком);

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, то есть проверка не прошла.

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

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

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

  • 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 – нет действия.

Алгоритмы распознают файлы с тегами из этого списка как подходящие для выполнения анализов Quality (Liveness) и Biometry.

Важно: в версии 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"
]

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

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

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

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

• OPERATOR – Системный оператор. Имеет неограниченный доступ на просмотр заявок и может принимать решения по анализам, с помощью кнопки Принять решение (обычно используется в случае появления статуса OPERATOR_REQUIRED);

• 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, но в рамках своей компании.

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

Компания

Папка

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

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

Отчет

Анализ

Коллекция

Персона

Фото персоны