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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Liveness

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этой статье вы найдете описание компонентов 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 вы найдете здесь.

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

Oz Liveness

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

Подтверждающие успешное прохождение тестов письма:

Также решение Oz Liveness прошло тест 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 соответствует стандартам SOC 2®.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пассивный Liveness

Активный Liveness

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

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

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

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, теги выставляются автоматически

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

Поскольку анализ видео может занять несколько секунд, анализы проводятся асинхронно. Сначала вы запускаете анализ (POST /api/folders/{{folder_id}}/analyses/), а затем следите за результатами, периодически запрашивая их с сервера, пока обработка не закончится (GET /api/analyses/{{analyse_id}} для определенного анализа или GET /api/folders/{{folder_id}}/analyses/ для всех анализов, назначенных на папку). Кроме того, можно использовать вебхуки. С примером опроса и использования вебхука можно ознакомиться здесь.

Более детальная информация о возможностях Oz API содержится в соответствующей секции нашего руководства разработчика.

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

Когда вы запускаете наши 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:

• Android

• iOS

Web SDK

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

Для выпуска лицензии Web SDK потребуется URL ваших доменов / поддоменов, где SDK будет использоваться. Для добавления лицензии в SDK поместите файл в тот же контейнер, как описано здесь. В редких случаях добавления лицензии возможно и через Web Plugin.

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

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

Для локальных установок мы выпускаем отдельную лицензию с ограничением по количеству активаций, где каждая активация соответствует отдельному экземпляру установки Oz BIO. Такая лицензия может работать и онлайн, и офлайн: это зависит от того, подключены ли к интернету соответствующие сервера. При онлайн-лицензировании SDK подключается к серверу лицензий для проверки, при офлайн потребуется установить офлайн-сервер лицензий. Мы поможем при установке сервера и активации лицензии.

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

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

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

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

Описание

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

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

• проводит авторизацию и распределение прав доступа

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

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

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

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

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

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

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

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

При создании папки добавьте нужный веб-адрес (resolution_endpoint) в раздел payload в теле запроса:

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

Для работы с Oz API Lite вы можете использовать свободно распространяемое ПО Postman. Скачайте клиентскую часть Postman по и установите ПО.

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

1.2.0

1.1.1

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

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

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

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

Обратите внимание: описанная ниже функциональность работает, начиная с версии 8.1.0.

Чтобы добавить или обновить языковой пакет для Oz iOS SDK, используйте метод set(languageBundle: Bundle). Он информирует SDK, что вы планируете использовать отличный от стандартного бандл. В OzLocalizationCode используйте кастомный язык (опционально).

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

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

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

Список переводов для iOS:

Ключи вида Action.*.Task относятся к соответствующим жестам. Остальные – к подсказкам для всех жестов, информационным сообщениям или ошибкам.

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

Oz Mobile SDK – Software Developer’s Kit системы Oz Forensics, обеспечивающий удобную интеграцию с мобильными приложениями для регистрации и биометрической идентификации клиентов.

Создайте контроллер для съемки видео:

action– перечень при записи видео.

По окончании съемки вызывается метод onOZLivenessResult(results:[OZMedia]):

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

Если пользователь прервет запись видео (закроет экран), появится ошибка failedBecauseUserCancelled.

Этот раздел описывает, как работать с Oz Flutter SDK для iOS и Android.

Перед началом работы мы рекомендуем установить:

• Flutter версии 3.0.0 или выше;

• Android SDK версии 21 или выше;

• dart версии 2.18.6 или выше;

• iOS версии 13 или выше;

• Xcode.

Образец кода для Flutter вы можете найти .

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

В этом разделе собрана информация о том, как управлять процессом работы с продуктами Oz Forensics со стороны клиента.

Обратите внимание: описанная ниже функциональность работает, начиная с версии 8.1.0.

Чтобы добавить или обновить языковой пакет для Oz Android SDK, сделайте следующие шаги:

1. Перейдите в папку для нужной локали или создайте такую папку. Детально процесс описан здесь.

2. Создайте файл и назовите его strings.xml.

3. Скопируйте строки из приложенного файла в только что созданный.

4. Переопределите в переводах строки, которые вам нужны.

Список переводов для Android:

Ключи вида action_*_go относятся к соответствующим жестам. Остальные – к подсказкам для всех жестов, информационным сообщениям или ошибкам.

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

Для подключения плагина на страницу необходимо добавить в html-код страницы ссылку на основной скрипт плагина (plugin_liveness.php). web-sdk-root-url – это полученная от нас ссылка на Web Adapter.

<script src="https://web-sdk-root-url/plugin_liveness.php"></script>

<link rel="stylesheet" href="https://web-sdk-root-url/plugin/ozliveness.css" />
<script src="https://web-sdk-root-url/plugin_liveness.php"></script>

Результат любого анализа представляет собой число. Для анализа 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-ответа.

Скрытие окна плагина без отмены callback'ов

Чтобы скрыть окно плагина, не отменяя запросы результатов анализов и пользовательские callback'и, воспользуйтесь методом hide(). Метод может пригодиться, если, к примеру, после отправки данных требуется вывести собственный индикатор загрузки.

OzLiveness.open({
  // При получении промежуточного результата скрываем окно плагина и показываем собственные индикаторы загрузки
  on_result: function(result) {
    OzLiveness.hide();
    if (result.state === 'processing') {
      show_my_loader();
    }
  },
  on_complete: function() {
    hide_my_loader();
  }
});

Закрытие плагина

Для принудительного закрытия окна плагина воспользуйтесь методом close(). При этом все запросы к серверу и callback-функции (кроме on_close) в рамках данной сессии будут остановлены.

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

var session_id = 123;

OzLiveness.open({
  // Передаем произвольные метаданные, по которым в дальнейшем сможем идентифицировать сессию в Oz API
  meta: {
    session_id: session_id 
  },
  // После отправки данных принудительно закрываем окно плагина и самостоятельно запрашиваем результат 
  on_submit: function() {
    OzLiveness.close();
    my_result_function(session_id);
  }
});

Если вы при обновлении с прежних версий (до 6.4.2 включительно) хотите сохранить привычный для клиентов дизайн, сбросьте настройки интерфейса экрана съемки до значений по умолчанию и примените следующие параметры (приведены только те параметры, которые нужно изменить):

// параметры настройки верхней панели
let toolbarCustomization = ToolbarCustomization(
   closeButtonColor: .white,
   backgroundColor: .black)

// параметры настройки текста подсказки
let centerHintCustomization = CenterHintCustomization(
   verticalPosition: 70)
   
// параметры настройки анимации подсказки
let hintAnimationCustomization = HintAnimationCustomization(
    hideAnimation: true)

// параметры настройки рамки вокруг лица
let faceFrameCustomization = FaceFrameCustomization(
   strokeWidth: 6,
   strokeFaceAlignedColor: .green,
   strokeFaceNotAlignedColor: .red)

// параметры настройки фона за рамкой
let backgroundCustomization = BackgroundCustomization(
   backgroundColor: .clear)

OZSDK.customization = OZCustomization(toolbarCustomization: toolbarCustomization,
   centerHintCustomization: centerHintCustomization,
   hintAnimationCustomization: hintAnimationCustomization,
   faceFrameCustomization: faceFrameCustomization,
   versionCustomization: versionCustomization,
   backgroundCustomization: backgroundCustomization)

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

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

В build.gradle модуля добавьте строки (VERSION – версия, которую вы планируете добавить. Список версий можно найти в Журнале изменений):

для анализов на сервере

dependencies {
  implementation 'com.ozforensics.liveness:sdk:VERSION'
}

для анализов и на сервере, и на устройстве

Обратите внимание: размер выходного файла будет больше.

dependencies {
implementation 'com.ozforensics.liveness:full:VERSION'
}

Вне зависимости от выбранного режима, добавьте еще:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

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

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

Второй вариант: логин и пароль.

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Ваш код для обработки ошибки или токена
}

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

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

let eventsConnection = Connection.fromCredentials(host: https://echo.cdn.ozforensics.com/,
                                login: <[email protected]>,
                                password: your_telemetry_password)
OZSDK.setEventsConnection(eventsConnection) { (token, error) in
}

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

• WA_ARCHITECTURE – переопределяет параметр architecture

• WA_API_URL – переопределяет параметр api_url

Пример использования переменных окружения при запуске docker-образа Web SDK в режиме Lite.

docker run -d -p 80:80 \
-e WA_ARCHITECTURE=lite \
-e WA_API_URL='http://127.0.0.1:8000/v1/face/liveness/detect' \
ozforensics/oz-webliveness:{tag}

Для работы плагина Oz Liveness браузер должен поддерживать JavaScript ES6. Версия браузера должна быть не ниже указанной в таблице.

*В режиме совместимости с Internet Explorer Web SDK работать не будет, так как не поддерживаются некоторые важные функции.

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

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

• [email protected]

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

Логин: [email protected]

Пароль: …

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 необходимо заменить на полученную от нас ссылку.

<script src="https://<web-adapter-url>/plugin_liveness.php"></script>

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

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

OzLiveness.open({
  lang: 'en',
  action: [
    // 'photo_id_front', // фото документа
    'video_selfie_blank' // видео с пассивным Liveness
  ],
  on_complete: function (result) {
    // эта функция вызывается по завершении анализа
    console.log('on_complete', result);
  }
});

Шаги выше помогут вам в базовой интеграции Web SDK в ваше веб-приложение. Чтобы получить доступ к снятым видео и результатам анализов, воспользуйтесь веб-консолью или API-запросами (получение видео в MP4 и результатов анализов).

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

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

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

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

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

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

Образец кода Oz Liveness Web SDK находится здесь. Чтобы все работало корректно, нужно заменить <web-adapter-url> на полученную от нас ссылку на Web Adapter.

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

• Образец кода для Angular

• Образец кода для React

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

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

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

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

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

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

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

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

• Для видео, записанного через Web SDK, процесс получения идентификатора папки описан здесь.

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

Android:

AnalysisRequest.Builder()
        ...
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                // сохраните folder_id, он потребуется далее
                val folderId = result.firstOrNull()?.folderId
            }
            ...
        })

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            ...
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    String folderId = list.get(0).getFolderId();
                    }
                }
                ...
    });
}

iOS:

analysisRequest.run(
scenarioStateHandler: { state in }, 
uploadProgressHandler: { (progress) in }  
)   { (analysisResults : [OzAnalysisResult], error) in 
        // сохраните folder_id, он потребуется далее
        let folderID = analysisResults.first?.folderID
    }
}

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

Вызовите метод POST /api/folders/{{folder_id}}/media/. Замените folder_id на полученный на предыдущем шаге идентификатор папки. Так ваше изображение попадет в папку с нужным видео.

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

{
  "media:tags": { 
    "photo1": [
        "photo_id", "photo_id_front" // для фото лицевой стороны документа
        // ИЛИ
        "photo_selfie" // для фото, не являющегося документом
    ]
  }
}

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

Для запуска анализа вызовите метод POST /api/folders/{{folder_id}}/analyses/. Замените folder_id на полученный ранее идентификатор папки. В теле запроса укажите анализ BIOMETRY.

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

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

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

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

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

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

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

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

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

Создание папки и добавление в нее медиафайлов: POST /api/folders/

Добавление файлов в существующую папку: POST /api/folders/{{folder_id}}/media/

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

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

{
    "media:tags": { // здесь устанавливаются теги для загружаемых вами медиафайлов
    // media files are referenced by the keys in a multipart form
        "video1": [ // ключ для файла
        // стандартный набор тегов для видео с пассивным Liveness
            "video_selfie", // видео с лицом
            "video_selfie_blank", // жест отсутствует
            "orientation_portrait" // ориентация видео
        ],
        "photo1": [
        // стандартный набор тегов для лицевой стороны документа
            "photo_id",
            "photo_id_front"
        ]
    }
}

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

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

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

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

6.0

Отдельная коллекция для Instant API:

5.3 и 5.2

5.0

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

4.0

3.33

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

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

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

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

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

Образец кода Oz Liveness Web SDK находится здесь. Чтобы все работало корректно, нужно заменить <web-adapter-url> на полученную от нас ссылку на Web Adapter.

В перечисленных ниже образцах кода нужно заменить ссылку https://web-sdk.sandbox.ozforensics.com в index.html.

• Образец кода для Angular

• Образец кода для React

• Образец кода для Vue

• Образец кода для Svelte

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

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

Body

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

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

headers = {‘ X-Forensic-Access-Token’: <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 в заголовках.

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

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

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

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

1. .

2. .

3. .

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

4а. Через некоторое время .

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

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

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

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

В версии 6.0.1 мы добавили новый режим работы API – Instant. В этом режиме мы не сохраняем никакие данные, все, что вы отправляете и получаете, существует только в рамках вашего запроса и ответа на него. Таким образом вы экономите место в хранилище и, что может быть особенно важно в рамках соблюдения требований законодательства, не передаете и не храните чувствительные данные.

Чтобы включить режим Instant API, при подготовке файла конфигурации (config.py) для API установите параметру OZ_APP_COMPONENTS значение stateless. Чтобы никакие данные запроса и ответа не сохранялись, отправьте следующий запрос: POST /api/instant/folders/ . Авторизация настраивается на вашей стороне.

При использовании Instant API с Web SDK при установите параметру architecture значение lite. Версия Web SDK должна быть не ниже 1.7.14.

Минимальные системные требования

• CPU: 16 ядер, 32 потока, базовая частота – 2.3 GHz, максимальная частота в турборежиме для одного ядра – 4 GHz.

• RAM: 32 GB, DDR 5, Dual Channel.

Для расчета RPS и RPM и подбора оптимальной конфигурации под ваши задачи обратитесь к нам.

Параметры конфигурации

Перед запуском подготовьте файл конфигурации со следующими параметрами.

Обязательные параметры

Без этих параметров Instant API не запустится.

Установка

Docker

Docker Compose

Методы Instant API

Список методов доступен по . Также вы можете скачать коллекцию для Postman:

Этот коллбэк вызывается раз в несколько секунд в процессе анализа и возвращает промежуточный результат (не применяется в режиме capture). Вид результата зависит от result_mode.

Safe

Если result_mode установлен как safe, коллбэк on_result возвращает только состояние анализов:

или

Status

При значении status коллбэк возвращает состояние анализов, а также – для каждого типа анализа – название типа, состояние анализа этого типа и вердикт системы.

или

Folder

При значенииfolderвозвращается практически то же самое, что при status, только добавляется идентификатор папки.

Full

В этом случае коллбэк возвращает полную информацию, включая чувствительные данные. Мы рекомендуем использовать safe; full будет отключен в ближайших релизах из соображений безопасности.

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

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

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

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

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

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

Для проверки корректности работы процессора Liveness используйте GET /v1/face/liveness/health.

Для проверки корректности работы процессора Biometry используйте GET /v1/face/pattern/health.

Чтобы выполнить liveness-проверку лица на изображении, вызовите POST /v1/face/liveness/detect (на вход принимает изображение, на выходе выводит оценку присутствия презентационной атаки на этом изображении).

Для сравнения лиц на двух изображениях вызовите POST /v1/face/pattern/extract_and_compare (принимает два изображения, извлекает из них биометрические шаблоны и сравнивает эти шаблоны). Также возможно сравнение одного изображения с несколькими с помощью POST /v1/face/pattern/extract_and_compare_n.

Полный список методов Oz API Lite с детальной информацией по ним вы можете найти .

Если наш SDK используется только для съемки, пропустите этот шаг.

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

Пример:

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

Добавление метаданных

Для добавления метаданных используйте метод AnalysisRequest.addFolderMeta.

Извлечение лучшего кадра

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

Использование медиафайла, снятого не нашим SDK

Чтобы использовать медиафайлы, снятые не Oz iOS SDK, укажите путь к ним в структуре (полеbestShotURL):

Добавление медиафайлов в определенную папку

Для добавления медиафайлов в определенную папку используйте метод addFolderId:

Получение и обработка результатов анализа на бэкенде

Результаты анализа доступны клиентскому приложению через функции-коллбэки Web Plugin, однако мы рекомендуем получать их через бэкенд напрямую от Oz API и там же обрабатывать впоследствии. Таким образом исключается вероятность манипуляций с результатами анализов через контекст браузера.

Чтобы найти нужную папку со стороны бэкенда, сделайте следующее:

1. На фронтенде добавьте уникальный идентификатор папки через метаданные:

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

2. Для оповещения о завершении анализа используйте функцию-коллбэк on_result, затем вызовите бэкенд и передайте значение transaction_id.

3. На стороне бэкенда найдите папку по присвоенному ранее идентификатору с помощью метода Folder LIST:

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

4. В ответе придут результаты анализов и идентификатор папки folder_id - он потребуется для дальнейших действий.

Ограничение объема данных, которые сервер отправляет Web Plugin

Web Adapter отправляет Web Plugin данные с различным уровнем детализации. Для продакшна рекомендуется установить минимальный уровень. Для этого в Web Adapter установите параметру result_mode значение "safe".

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

Укажите информацию о лицензии одним из двух способов:

• через данные о лицензии:

• через путь к лицензии:

Проверьте, как установилась лицензия: например, пройдите по доменному имени хоста и выполните действие Liveness -> Simple selfie.

Далее при каждом запуске Web SDK система будет проверять валидность лицензии.

Чтобы начать пользоваться нашим SDK, нужно выполнить следующие шаги.

1. Добавьте SDK в проект, как описано .

2. Получите лицензию на SDK – сгенерируйте тестовую самостоятельно на нашем или запросите «боевую» по . Для лицензии потребуется bundle id. Добавьте лицензию в проект, как описано .

3. SDK к API. Это необязательный шаг, он выполняется, только если вам нужно обрабатывать какие-либо данные на сервере. Если вы используете , никакие данные никуда не передаются, и подключение к API не нужно.

4. Создайте контроллер для съемки, как описано – вы получите медиафайлы, которые потом можно будет отправить на анализ.

5. Запустите нужные вам проверки для полученных на предыдущем шаге медиафайлов. описано, как выполнять проверки.

6. Если вы хотите настроить внешний вид SDK, написано, как это делается.

Ресурсы

Минимальная версия iOS: 11.

Минимальная версия Xcode: 16.

Доступные языки: EN, RU, ES, HY, KK, KY, TR.

Исходный код примера приложения с использованием Oz Liveness SDK расположен в репозитории GitLab:

Список методов и полей SDK:

Актуальную сборку демо-приложения Вы можете загрузить по .

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

Установка по шагам

Для установки требуется любой стационарный (не виртуальный) сервер с ОС Linux. , чтобы получить архив с программой, и следуйте инструкции ниже.

1. Распакуйте архив

2. Установите службу лицензирования

На этом серверная установка окончена. Дальнейшая настройка и активация производится через Web-интерфейс на порту 8090.

3. Активируйте лицензию

Откройте в браузере страницу по адресу http://server:8090 и авторизуйтесь.

Зайдите в раздел Settings.

Онлайн-активация

Наиболее простой способ активировать сервер лицензирования – выполнить это онлайн.

Для этого достаточно ввести ключ и нажать ACTIVATE.

Офлайн-активация

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

Для этого нажмите SWITCH TO OFFLINE ACTIVATION.

Введите ключ и нажмите NEXT.

Затем нажмите DOWNLOAD REQUEST FILE.

файл offline_activation_request.txt . Мы в ответ направим вам код активации.

Введите этот код в окно для offline activation response и нажмите ACTIVATE.

Настройка Oz Liveness WEB Adapter производится путем изменения конфигурационного файла, расположенного на сервере Oz Liveness WEB Adapter по пути /core/app_config.json

Образец кода Oz Liveness Web SDK находится . Чтобы все работало корректно, нужно заменить <web-adapter-url> на полученную от нас ссылку на Web Adapter.

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

• Образец кода для

• Образец кода для

CocoaPods

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

VERSION (опционально, по умолчанию устанавливается последняя версия) – версия, которую можно найти в .

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

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

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

SPM

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

Добавьте через SPM зависимости пакетов по ссылке: (, как добавить зависимости). Файл OzLivenessSDK обязателен для добавления, OzLivenessSDKOnDevice можно не добавлять, если вы не используете анализы на устройстве.

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

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

1. Скачайте следующие файлы и добавьте их в проект:

• OZLivenessSDK.xcframework,

• OZLivenessSDKResources.bundle,

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

1. Скачайте TensorFlow : потребуется версия 2.11.

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

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

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

Алгоритм "лучший кадр" выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу 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

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

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

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

  • 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"
]

Обзор

При создании какого-либо объекта системы у вас может возникнуть необходимость хранить для него дополнительные данные, те, которые отсутствуют в базовом списке его параметров. Такие данные называются метаданными. Вы можете хранить любую нужную вам информацию в разделе meta_data в приведенном ниже формате ("название поля": "соответствующие полю данные"):

…
meta_data:
{
  "field1": "value1",
  "field2": "value2"
}
…

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

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

Метаданные можно также и менять, и удалять. Все нужные методы описаны в нашей документации по API.

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

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

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

{
  "iin": "123123123"
}

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

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

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

• iOS

• Android

• Web

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

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

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

Второй вариант: логин и пароль.

OzLivenessSDK.setApiConnection(
    OzConnection.fromCredentials(host, username, password),
    statusListener(
        { token -> /* токен */ },
        { ex -> /* ошибка */ }
    )
)

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) { /* токен */ }
            @Override
            public void onError(@NonNull OzException e) { /* ошибка */ }
        }
);

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

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

OzLivenessSDK.setEventsConnection(
    OzConnection.fromCredentials(
        "https://echo.cdn.ozforensics.com/",
        "<[email protected]>",
        "your_telemetry_password"
    )
)

OzLivenessSDK.setEventsConnection(
        OzConnection.fromCredentials(
                "https://tm.ozforensics.com/",
                "<[email protected]>",
                "your_telemetry_password"
        )
);

Очистка авторизации:

OzLivenessSDK.setApiConnection(null)

OzLivenessSDK.INSTANCE.setApiConnection(null, null);

Проверка наличия сохраненного access-токена Oz API:

val isLoggedIn = OzLivenessSDK.isLoggedIn

boolean isLoggedIn = OzLivenessSDK.INSTANCE.isLoggedIn();

LogOut:

OzLivenessSDK.logout()

OzLivenessSDK.INSTANCE.logout();

1.2.3 – 21.11.2024

• Исправили ошибку, иногда возникавшую при генерации параметров time_created и folder_id метода Detect.

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

1.2.2 – 17.10.2024

• Обновили модели.

1.2.1 – 05.09.2024

• С помощью метода Liveness detect теперь можно отправить не более 10 файлов в одном запросе, при этом размер каждого файла не должен превышать 15 МБайт.

• Обновили список жестов, которые поддерживают отправку лучшего кадра (best_shot): включили повороты, наклон и подъем головы, а также улыбку и моргание.

1.2.0 – 26.07.2024

• Обновили метод Liveness detect: теперь он работает также и с видео и архивами.

1.1.1 – 28.11.2022

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

1.1.0

• API Lite теперь работает и с base64

09.2021

• Улучшили биометрическую модель

• Добавили режим 1:N

08.2021

• Добавили политику CORS

• Подготовили первую версию документации

06.2021

• Переработали сообщения об ошибках, теперь они более информативны

• Упростили операции Liveness/Detect

04.2021

• Переработали ядро

• Добавили операции для защиты от спуфинга

10.2020

• Добавили операцию extract_and_compare

Для настройки интерфейса воспользуйтесь разделом style в методе Ozliveness.open. Изменить можно следующие настройки:

• faceFrame – цвет рамки вокруг лица:

  • faceReady – цвет рамки при правильном расположении лица;

  • faceNotReady – цвет рамки при неправильном положении лица, когда анализ не может быть запущен.

• centerHint – текст подсказки в центре.

  • textSize – размер текста;

  • color – цвет текста;

  • yPosition – позиция по вертикали относительно верха контейнера;

  • letterSpacing – расстояние между буквами;

  • fontStyle – стиль текста (полужирный, курсив и так далее).

• closeButton – кнопка закрытия плагина:

  • image – изображение для кнопки, может быть картинкой в формате PNG или dataURL в base64.

• backgroundOutsideFrame – заливка вне рамки вокруг лица:

  • color – цвет заливки.

Пример:

OzLiveness.open({
  // ...
  style: {
	  //блок для обратной совместимости
    doc_color: "", 
    face_color_success: "",
    face_color_fail: "", 
	//основной блок
    faceFrame: {
      faceReady: "",
      faceNotReady: "",
    },
    centerHint: {
      textSize: "",
      color: "",
      yPosition: "",
      letterSpacing: "", 
      fontStyle: "", 
    },
    closeButton: {
      image: "",
    },
    backgroundOutsideFrame: {
      color: "", 
    },
  },
  // ...
});

Для добавления нового языкового пакета или модификации существующего следует воспользоваться методом add_lang(lang_id, lang_obj).

Параметры:

• lang_id – строковое значение, которое далее можно использовать в качестве параметра lang метода open();

• lang_obj– объект, ключами которого являются идентификаторы строк перевода, а значениями – сами строки перевода.

Список идентификаторов языков:

*До версии 1.3.1 назывался pt.

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

OzLiveness.add_lang('ru', ruTranslation), гдеruTranslation – объект JSON.

// Редактируем текст кнопки
OzLiveness.add_lang('ru', {
  action_photo_button: 'Сделать фото'
});

Для установки нужного языка укажите его идентификатор в lang:

OzLiveness.open({
    lang: 'es', // идентификатор нужного языка
    ...
});

Вы можете запросить, какие языковые пакеты установлены в Web SDK, с помощью метода ozLiveness.get_langs(). Добавленные вручную локали также отобразятся.

Список всех строковых идентификаторов:

Ключи вида oz_action_*_go относятся к соответствующим жестам. oz_tutorial_camera_* – к подсказкам, как включить камеру для различных браузеров. Остальные – к подсказкам для всех жестов, информационным сообщениям или ошибкам.

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

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

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

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",
    {
    .... // информация о папке и т.д.
    }
}

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

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

Этот коллбэк вызывается после окончания проверки и возвращает результат анализа (не применяется в режиме capture). Вид результата зависит от параметра настройки Web Adapter result_mode.

Safe

Если result_mode установлен как safe, коллбэкon_complete возвращает только состояние анализов:

{
  "state": "finished"
}

Status

При значении status коллбэк возвращает состояние анализов, а также – для каждого типа анализа – название типа, состояние анализа этого типа и вердикт системы.

{
 "state": "finished",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "success"
   }
 }
}

Folder

При значенииfolderвозвращается практически то же самое, что при status, только добавляется идентификатор папки.

{
 "state": "finished",
 "folder_id": "your_folder_id",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "success"
   }
 }
}

Full

В этом случае коллбэк возвращает полную информацию, включая чувствительные данные. Мы рекомендуем использовать safe; full будет отключен в ближайших релизах из соображений безопасности.

Если вы при обновлении с прежних версий (до 6.4.2 включительно) хотите сохранить привычный для клиентов дизайн, сбросьте настройки интерфейса экрана съемки до значений по умолчанию и примените следующие параметры (приведены только те параметры, которые нужно изменить):

OzLivenessSDK.config.customization = UICustomization(
    // параметры настройки верхней панели
    toolbarCustomization = ToolbarCustomization(
        closeIconTint = Color.ColorHex("#FFFFFF"),
        backgroundColor = Color.ColorHex("#000000"),
        backgroundAlpha = 100,
    ),
    // параметры настройки текста подсказки
    centerHintCustomization = CenterHintCustomization(
        verticalPosition = 70
    ),
    hintAnimation = HintAnimation(
    hideAnimation = true
),
    // параметры настройки рамки вокруг лица
    faceFrameCustomization = FaceFrameCustomization(
        strokeDefaultColor = Color.ColorHex("#EC574B"),
        strokeFaceInFrameColor = Color.ColorHex("#00FF00"),
        strokeWidth = 6,
    ),
    // параметры настройки фона за рамкой
    backgroundCustomization = BackgroundCustomization(
        backgroundAlpha = 100
    ),
)

OzLivenessSDK.INSTANCE.getConfig().setCustomization(new UICustomization(
// параметры настройки верхней панели
new ToolbarCustomization(
    R.drawable.ib_close,
    new Color.ColorHex("#FFFFFF"),
    new Color.ColorHex("#000000"),
    100, // непрозрачность фона верхней панели (в %)
    ),
// параметры настройки текста подсказки
new CenterHintCustomization(
    70, // положение по вертикали (в %)
),
// параметры настройки анимации подсказки
new HintAnimation(
    hideAnimation = true
),
// параметры настройки рамки вокруг лица
new FaceFrameCustomization(     
    new Color.ColorHex("#EC574B"), 
    new Color.ColorHex("#00FF00"),
    6, // ширина линии рамки (в dp)
 ),
// параметры настройки фона за рамкой
new BackgroundCustomization(
    100 // непрозрачность фона (в %)
),
  )
);

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

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

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

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

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

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

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

OzLiveness.open({
  lang: 'en',
  action: [
    'photo_id_front', 
    'video_selfie_blank'
  ],
  ...
});

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

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

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

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {

    val refFile = File(context.filesDir, "reference.jpg")
    val refMedia = OzAbstractMedia.OzDocumentPhoto(
        OzMediaTag.PhotoIdFront , // OzMediaTag.PhotoSelfie для не являющегося документом фото
        refFile.absolutePath
    )

    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList))
        .addAnalysis(Analysis(Analysis.Type.BIOMETRY, Analysis.Mode.SERVER_BASED, mediaList + refMedia))
        .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) {
    File refFile = new File(context.getFilesDir(), "reference.jpg");
    OzAbstractMedia refMedia = new OzAbstractMedia.OzDocumentPhoto(
            OzMediaTag.PhotoIdFront , // OzMediaTag.PhotoSelfie for a non-ID photo
            refFile.getAbsolutePath()
    );
    ArrayList<OzAbstractMedia> mediaWithReferencePhoto = new ArrayList<>(mediaList);
    mediaWithReferencePhoto.add(refMedia);
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList, Collections.emptyMap()))
            .addAnalysis(new Analysis(Analysis.Type.BIOMETRY, Analysis.Mode.SERVER_BASED, mediaWithReferencePhoto, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    String folderId = list.get(0).getFolderId();
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

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

Код образца для Android находится здесь.

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

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

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

let imageURL = URL(fileURLWithPath: NSTemporaryDirectory())
    .appendingPathComponent("reference.jpg")

let refMedia = OZMedia.init(movement: .selfie,
                   mediaType: .movement,
                   metaData: nil,
                   videoURL: nil,
                   bestShotURL: imageUrl,
                   preferredMediaURL: nil,
                   timestamp: Date())
   
var mediaBiometry = [OZMedia]()
mediaBiometry.append(refMedia)
mediaBiometry.append(contentsOf: mediaToAnalyze)
let analysisRequest = AnalysisRequestBuilder()
let analysisBiometry = Analysis.init(media: mediaBiometry, type: .biometry, mode: .serverBased)
let analysisQuality = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
analysisRequest.addAnalysis(analysisBiometry)
analysisRequest.addAnalysis(analysisQuality)
analysisRequest.uploadMedia(mediaBiometry)
analysisRequest.run(
    scenarioStateHandler: { state in }, // обработчик шагов сценария
    uploadProgressHandler: { (progress) in } // обработчик для загрузки файлов
) { (analysisResults : [OzAnalysisResult], error) in
    // получение и обработка анализов
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

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

Код образца для iOS находится здесь.

Для всех SDK

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

Методы как API, так и SDK могут гибко комбинироваться. Подробнее об этом вы можете прочитать в руководстве разработчика.

Чтобы начать пользоваться нашим SDK, нужно выполнить следующие шаги.

1. Добавьте SDK в проект, как описано здесь.

2. Получите лицензию на SDK – сгенерируйте тестовую самостоятельно на нашем сайте или запросите «боевую» по электронной почте. Для лицензии потребуется application id. Добавьте лицензию в проект, как описано здесь.

3. Подключите SDK к API. Это необязательный шаг, он выполняется, только если вам нужно обрабатывать какие-либо данные на сервере.

4. Для съемки видео используйте методы, описанные здесь – вы получите медиафайлы, которые потом можно будет отправить на анализ.

5. Запустите нужные вам проверки для полученных на предыдущем шаге медиафайлов. Здесь описано, как выполнять проверки.

6. Если вы хотите настроить внешний вид SDK, здесь написано, как это делается.

Ресурсы

Рекомендуемая версия Android: 5+ (чем новее смартфон, тем быстрее выполняются анализы).

Рекомендуемые версии компонентов:

Мы не поддерживаем эмуляторы.

Доступные языки: EN, RU, ES, HY, KK, KY, TR.

Исходные коды примеров приложений с использованием Oz Liveness SDK расположены в репозитории GitLab:

Список методов и полей SDK:

Актуальную сборку демо-приложения Вы можете загрузить по ссылке.

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

• ,

• ,

• ,

• .

Biometry

Назначение

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

Результат

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

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

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

Quality (Liveness, Best Shot)

Назначение

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

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

Результат

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

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

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

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

Documents

Назначение

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

Результат

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

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

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

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

Blacklist

Назначение

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

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

Результат

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

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

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

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

Порядок действий описан ниже.

1. Авторизуйтесь. Параметры передаются в json-запросе в составе credentials. См. статьи и .

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

Пример заполнения payload для видео:

3. Запустите анализ: POST/api/folders/{{folder_id}}/analyses/

В типе анализа должно быть указано collection.

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

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

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

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

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

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

Если вы хотите узнать, с кем именно из вашей базы фотографий совпало лицо с медиафайла, который вы только что загрузили, найдите в ответе анализ collection, в нем results_media, где и будет идентификатор нужной вам персоны person_id. Чтобы получить информацию об этой персоне, вызовите метод GET /api/collections/{{collection_id}}/persons/{{person_id}}, указав идентификаторы вашей коллекции и персоны в ней.

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

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

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

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

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

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

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

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

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

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

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

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

Вы также можете загрузить дополнительные фото персоны после ее добавления: используйте метод 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}}/.

Установка

Установить SDK можно двумя способами: либо инженеры Oz Forensics делают все вручную, либо используется . В последнем случае потребуется вовлечение ваших специалистов. При установке Oz Web SDK Web Adapter сгенерирует нужные файлы Web Plugin: такие, как файл со стилями (ozliveness.css) и основной скрипт плагина (plugin_liveness.php).

Лицензирование

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

1. Распакуйте полученный файл.

2. Скопируйте JSON-файл лицензии на хост, где развернут контейнер из образа ozforensics/oz-webliveness-dev:latest.

Пример

• -i ~/ozforensics/keys/id_rsa-test-hostname-vm – путь к публичному ssh-ключу хоста

• 0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json – файл лицензии в формате JSON.

• user – имя пользователя на хосте.

• hostname – псевдоним хоста.

• /opt/oz/web-sdk – каталог на хосте, где развернут контейнер Web SDK.

3. Замените файл лицензии.

Пример

4. Перезапустите контейнер Web SDK.

Пример

• web-sdk – название контейнера, созданного из образа ozforensics/oz-webliveness-dev:latest.

Проверьте, как установилась лицензия: например, пройдите по доменному имени хоста и выполните действие Liveness -> Simple selfie.

Далее при каждом запуске Web SDK система будет проверять валидность лицензии. Чтобы выполнить проверку вручную, воспользуйтесь методом [GET] /check_license.php.

Возможные ошибки лицензирования

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

1. Переименуйте файл в forensics.license и поместите его в проект. Прописывать путь в этом случае не нужно.

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

или

LicenseSource – источник лицензии, LicenseData – информация о лицензии. В этот метод встроена проверка наличия активной лицензии, если такая лицензия есть – будет использоваться она, а не та, путь к которой вы указали. Для принудительной замены лицензии используйте метод setLicense.

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

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

Настройка интерфейса

Чтобы настроить интерфейс Oz Liveness, воспользуйтесь OZCustomization. Полный список полей находится .

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

Генерация ключей

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

Создание приватного ключа

Чтобы создать приватный ключ, последовательно запустите следующие команды:

openssl genpkey -algorithm RSA -outform DER -out privateKey.der -pkeyopt rsa_keygen_bits:2048
# for MacOS
base64 -i privateKey.der -o privateKey.txt
# for Linux 
base64 -w 0 privateKey.der > privateKey.txt

Вы получите два файла:

• privateKey.der – приватный ключ .der;

• privateKey.txt – privateKey.der в кодировке base64. Содержимое этого файла используется в качестве подписи bundle_id хостового приложения.

Спецификация команд OpenSSL: https://www.openssl.org/docs/man1.1.1/man1/openssl-pkcs8.html

Создание публичного ключа

Чтобы создать публичный ключ, запустите команду:

openssl rsa -pubout -in privateKey.der -out publicKey.pub

Вы получите публичный ключ publicKey.pub. Отправьте его нам по электронной почте. В ответ мы пришлем вам лицензию.

Интеграция SDK

Инициализация SDK:

fun init(
    context: Context,
    licenseSources: List<LicenseSource>,
    masterLicenseSignature: String,
    statusListener: StatusListener<LicensePayload>? = null,
 )

Перед инициализацией SDK создайте закодированную base64 подпись для bundle_id хостового приложения с помощью приватного ключа.

Пример создания подписи:

private fun getMasterSignature(): String {
    Security.insertProviderAt(org.spongycastle.jce.provider.BouncyCastleProvider(), 1)

    val privateKeyBase64String = "содержимое файла privateKey.txt"

    val sig = Signature.getInstance("SHA512WithRSA")
    val keySpec = PKCS8EncodedKeySpec(Base64.decode(privateKeyBase64String, Base64.DEFAULT))
    val keyFactory = KeyFactory.getInstance("RSA")
    sig.initSign(keyFactory.generatePrivate(keySpec))
    sig.update(packageName.toByteArray(Charsets.UTF_8))
    return Base64.encodeToString(sig.sign(), Base64.DEFAULT).replace("\n", "")
 }

KohJ1rsUgLMzZHpHGAZDK2efHPnMj9tw9VIedBLvyZt0B2JH3SWfJLJ8X6JNz3bR2sce6PR2wdEIFln0r1pUnD+6WBCgexKIHAv7esiRVQZoZOEANDBwDvJVv73H/0qL2LGlhxKzbBg5CxGPClTBQdLo1P+7HsTXHHG/Hf6m3rdu1OUeGXVPoaS2NzE8kiRH6gb8Nhr7PBLTUeMKTeLoiX13hvwjOqhV1ANhgS97T4hC2+ZilZt4RektgRY/+fGmWnOqErNeYuz/WSInfaJS0YEWhJW3gXKPjdCzNGIBIqbxaFSjU46wu/alh2+tBRFnrYFl1dRQVcTlW0VwwZHcug==

Передайте подпись как параметр masterLicenseSignature во время инициализации SDK.

Если подпись невалидна, инициализация продолжится по стандартной схеме: проверка включенных в лицензию bundle_id.

Сгенерируйте тестовую лицензию самостоятельно здесь (внимание, страница на английском языке) или свяжитесь с нами по email для выпуска продуктивной лицензии. Для подготовки лицензии потребуется applicationId (bundle id).

Для добавления файла лицензии в SDK вызовите метод OzLivenessSDK.init с одним из параметров LicenseSources:

• LicenseSource.LicenseAssetId должен содержать путь к файлу forensics.license, расположенному в проекте в папке res/raw.

• LicenseSource.LicenseFilePath должен содержать пусть к файлу на устройстве (вне проекта).

OzLivenessSDK.init(context,
    listOf(
        LicenseSource.LicenseAssetId(R.raw.your_license_name),
        LicenseSource.LicenseFilePath("абсолютный путь к файлу лицензии")
    ),
    object : StatusListener<LicensePayload> {
        override fun onSuccess(result: LicensePayload) { /*проверка информации о лицензии*/ }
        override fun onError(error: OzException) { /*обработка исключения */ }
    }
  )

OzLivenessSDK.INSTANCE.getConfig().setBaseURL(BASE_URL);
OzLivenessSDK.INSTANCE.init(context,
    Arrays.asList(
        new LicenseSource.LicenseAssetId(R.raw.forensics),
        new LicenseSource.LicenseFilePath("aбсолютный путь к файлу лицензии")
    ),
    new StatusListener<LicensePayload>() {
        @Override public void onStatusChanged(@Nullable String s) {}
        @Override public void onSuccess(LicensePayload licensePayload) { /*проверка информации о лицензии*/ }
        @Override public void onError(@NonNull OzException e) { /*обработка исключения */ }
    }
);

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

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