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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.2.0

1.1.1

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

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

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

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

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

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

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

1. .

2. .

3. .

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

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

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

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

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

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

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

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

2. .

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

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

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

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

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

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

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

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

Описание

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

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

• проводит и

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Авторизуйтесь. Параметры передаются в json-запросе в составе credentials. См. статьи Коллекции Postman и Аутентификация.

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

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

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

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

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

{
    "analyses": [{
    "type": "collection",
    "source_media": ["идентификатор_медиафайла_источника"],
  }]
}

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

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

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

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

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

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

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

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

Чтобы провести анализы для ваших медиафайлов, необходимо поместить их в папку – либо существующую, либо новую, созданную с помощью 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):

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

В версии 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:

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 с детальной информацией по ним вы можете найти .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

{
  "iin": "123123123"
}

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

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

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

• iOS

• Android

• Web

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

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

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

Body

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

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

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

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

Действие access_token ограничено во времени и регулируется настройками:

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

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

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

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

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

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

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

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

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

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

Чтобы начать пользоваться нашим 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Преимущества

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

• Синхронная работа – как только анализ завершится, вы получите результат, не нужно опрашивать сервер о готовности или настраивать вебхуки.

• Высокая производительность – до 36 анализов в минуту на один сервер.

Использование

Чтобы отправить медиафайлы на анализ одним запросом, вызовите метод POST /api/folders/. В заголовке X-Forensic-Access-Token передайте ваш . Добавьте в тело запроса нужные медиафайлы, а в payload – соответствующие им теги и, если нужно, метаданные.

Пример запроса

Пример ответа

В ответе вам придут результаты анализов.

Готово.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

on_error { 
    "code": "error_code", 
    "event_session_id": "id_of_telemetry_session_with_error", 
    "message": "<error decription>", 
    "context": {}  // дополнительная информация
}

Если вы при обновлении с прежних версий (до 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)

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

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

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

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

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

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

• Xcode.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Коды HTTP-ответов

• Коды ответов в диапазоне 2XX соответствуют корректно отработавшему запросу (например, при получении данных возвращается код 200, при добавлении новой сущности – 201, при корректном удалении – 204 и так далее);

• Коды ответов в диапазоне 4XX соответствуют ошибке при обработке запроса, произошедшей на стороне вызывающего клиента (например, 404 – обращение к несуществующему ресурсу);

• Коды ответов в диапазоне 5XX соответствуют ошибке при обработке запроса на стороне самой системы (например, при временной недоступности базы данных).

Тело ответа при ошибке

Каждая ошибка, возникшая при обработке запроса на стороне системы, помимо соответствующего HTTP-кода ошибки содержит также описание самой ошибки в теле ответа с указанием следующих JSON-полей:

• error_code – целочисленный код ошибки;

• error_message– сообщение с описанием возникшей ошибки (используется только для отладочных задач и расследования инцидентов);

• details – детали ошибки (приводятся в произвольном формате, специфичном для каждого отдельного типа ошибки). Необязательное поле.

Пример ответа сервера:

Коды ошибок:

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

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

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

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

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

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

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

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

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

Safe

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

Status

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

Folder

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

Full

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

При работе с 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

или

OZSDK(licenseSources: [.licenseFilePath(“path_to_file”)]) { licenseData, error in
      if let error = error {
        print(error)
      }
    }

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

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

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

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

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

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

OzLiveness.open({
    license: {
        'payload_b64': 'some_payload',
        'signature': 'some_data',
        'enc_public_key': 'some_key'
    },
    ...,
})

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

OzLiveness.open({
    licenseUrl: 'https://some_url',
    ...,
})

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

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

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

let actions: [OZVerificationMovement] = [.scanning, .smile, .far]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(self, actions: actions)
self.present(ozLivenessVC, animated: true)

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

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

extension viewController: OZLivenessDelegate {
 func onError(status: OZVerificationStatus?) {
        //показать ошибку
   }
 }
 func onOZLivenessResult(mediaToAnalyze: [OZMedia]) {
   //Перейти к выполнению проверки
 }
}

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

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

Для работы с 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:

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

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

Пример работы:

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

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

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

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

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

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

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

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

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

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

Safe

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

или

Status

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

или

Folder

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

Full

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

8.18.1 – 10.09.2025

• initSDK в дебаг-режиме для iOS теперь работает корректно.

8.18.0 – 26.08.2025

• Добавили возможность выполнять .

• Исправили ошибку в коде примера.

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

• При попытке удалить референтное фото SDK теперь запрашивает подтверждение.

• Исправили ошибку с темным фоном при запуске SDK.

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

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

• Android: теперь поддерживаем Google Dynamic Feature Delivery.

• Android: исправили ошибку, из-за которой SDK мог вылететь при закрытии экрана съемки.

• iOS: исправили ошибку с интеграцией через Swift UI.

• iOS: в соответствии с требованиями Apple обновили Xcode до версии 16.

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

8.16.0 – 30.04.2025

• Обновили логику авторизации.

• Улучшили логику озвучивания подсказок.

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

• Android: валидацию видео – опцию, которая запускает запись видео заново, если получившийся файл состоит из 3 кадров и менее – теперь можно отключить.

• iOS: SDK теперь сжимает медиафайлы, если их размер превышает 10 МБ.

• iOS: жесты с движениями головы теперь обрабатываются корректно.

• iOS: в соответствии с требованиями Apple обновили Xcode до версии 16.

8.14.0 – 17.12.2024

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

• Подсказки SDK и элементы управления интерфейса могут озвучиваться в соответствии с требованиями WCAG.

• Упростили прохождение проверки для жестов, включающих движение головы.

• Android: сжатие больших видео теперь происходит на этапе закрытия экрана Liveness.

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

• Android: исправили проблемы с кодеками, появлявшиеся на некоторых моделях смартфонов.

• Android: исправили ошибку, из-за которой некоторые записанные SDK видео были зелеными.

• iOS: добавили поддержку Xcode 16.

• iOS: при использовании основной (задней) камеры яркость экрана теперь не меняется.

• iOS: исправили ошибку записи видео, появлявшуюся на некоторых моделях смартфонов.

8.12.0 – 11.10.2024

• Метод executeLiveness больше не используется. Съемка теперь запускается с помощью метода startLiveness.

• Обновили код для получения результата съемки.

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

8.8.2 – 27.06.2024

• При попытке передать пустую строку в качестве аргумента для методов addFolderId (iOS) и setFolderID (Android)теперь показывается информативная ошибка.

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

• Android: исправили несколько ошибок, появлявшихся только на определенных моделях смартфонов.

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

8.6.0 – 15.04.2024

• Android: улучшили модель Liveness для проверки на устройстве.

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

• iOS: синхронизировали с Android сообщения, которые SDK показывает после загрузки медиафайла.

• iOS: исправили баг с задержками запуска анализа, которые иногда возникали для анализа по одному кадру.

8.5.0 – 20.03.2024

• Длительность жеста Селфи теперь можно менять (размер видеофайла также изменится).

• Убрали паузу после жеста Сканирование.

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

• Android: если размер записанного видеофайла больше 10 Мбайт, видео будет сжато.

8.4.0 – 11.01.2024

• Android: обновили модель Liveness для проверки на устройстве.

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

• Исправили ошибки.

8.3.0 – 30.11.2023

• Добавили возможность использования мастер-лицензии, которая работает с любым bundle_id.

• Android: исправили ошибку со сжатием видео при гибридном анализе, которая возникала на некоторых моделях телефонов.

• iOS: исправили ошибку с мигающим фоном при съемке.

8.2.0 – 17.11.2023

• Выпущена первая версия.

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

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

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

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

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

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

LogOut:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

Результаты анализа доступны клиентскому приложению через функции-коллбэки 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".

Мастер-лицензия – это оффлайн-лицензия, с которой можно использовать мобильные 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.pem -out publicKey.pub
base64 -w 0 publicKey.pub > publicKey.txt

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

Интеграция SDK

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

OZSDK(licenseSources: [LicenseSource], masterLicenseSignature: String? = nil, completion: @escaping ((LicenseData?, LicenseError?) -> Void))

Установка лицензии:

setLicense(licenseSource: LicenseSource, masterLicenseSignature: String? = nil)

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

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

private func getSignature() -> String? {
    let privateKeyBase64String = "содержимое файла privateKey.txt"
 
    guard let data = Data(base64Encoded: privateKeyBase64String, options: [.ignoreUnknownCharacters]) else {
      return nil
    }
     
    let sizeInBits = data.count * 8
    let keyDict: [CFString: Any] = [
      kSecAttrKeyType: kSecAttrKeyTypeRSA,
      kSecAttrKeyClass: kSecAttrKeyClassPrivate,
      kSecAttrKeySizeInBits: NSNumber(value: sizeInBits)
    ]
     
    var error: Unmanaged<CFError>?
    guard let secKey = SecKeyCreateWithData(data as CFData, keyDict as CFDictionary, &error) else {
      return nil
    }
     
    guard let bundleID = Bundle.main.bundleIdentifier else {
      return nil
    }
    guard let signature = SecKeyCreateSignature(secKey,
                          .rsaSignatureMessagePKCS1v15SHA512,  // Это критично!!!!
                          Data(bundleID.utf8) as CFData,
                          &error) else {
      return nil
    }
    return (signature as Data).base64EncodedString()
  }

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

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

Чтобы начать пользоваться нашим 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:

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

Для старта записи видео используется метод startActivityForResult:

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

Для представления Fragment код приведен ниже. LivenessFragment – для экрана Liveness.

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

• sdkMediaResult – объект с результатами записи видео () для дальнейшего использования при взаимодействии с Oz API.

• sdkErrorString – описание в случае их возникновения.

Если пользователь прервет запись видео (закроет экран), resultCode примет значение Activity.RESULT_CANCELED.

Пример кода для обработки:

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

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

Oz Liveness Web SDK представляет собой модуль съемки и отправки медиаданных на анализы из веб-браузера на клиентском устройстве. Поддерживаются все основные браузеры на большинстве устройств. Доступные языки: EN, RU, ES, PT-BR, KK.

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

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

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

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

Web SDK только работает по протоколу HTTPS (с SSL-шифрованием); на localhost и 127.0.01 можно использовать HTTP для проверки доступности ресурсов.

Oz Liveness Web SDK состоит из двух частей:

1. Клиентская – . Используется в виде подгружаемого JavaScript-файла в Frontend-приложении клиента.

2. Серверная – . Устанавливается в виде отдельного серверного модуля с привязкой к .

Руководства по интеграции:

Oz Web SDK можно развернуть как , так и на наших (SaaS), в последнем случае разворачиваем и поддерживаем программное обеспечение мы, а вы пользуетесь уже готовым и настроенным продуктом. для выбора более удобного варианта.

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

Пошаговая инструкция по использованию Web SDK:

1. плагин в свою страницу.

2. Если вы хотите настроить интерфейс Oz Web SDK под себя, рассказано, как это сделать.

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

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

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

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

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

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

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

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

Спецификация команд OpenSSL:

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

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

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

Интеграция SDK

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

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

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

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

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

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

В последнем случае система автоматически определяет, какие именно анализы должны запускаться для того или иного медиафайла. При этом она исходит из того, какие указаны при загрузке файлов. Если файлы загружаются через web-консоль, теги расставляет пользователь, если ведется съемка через SDK – теги проставляются в процессе съемки также автоматически. Также роль играет тип медиафайлов: IMAGE (фото)/VIDEO/SHOTS_SET (приравнивается к видео). Если медиафайл не подходит под требования того или иного анализа, этот анализ такой медиафайл игнорирует.

Список настроек по умолчанию приведен ниже. Для изменения конфигурации, пожалуйста, .

Анализ выполняется для всех медиафайлов вне зависимости от воспроизводимого в них (теги жестов начинаются с video_selfie).

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

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

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

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

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

Documents

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

• паспорт

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

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

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