Как интегрировать Oz Liveness с использованием Instant API (режима без сохранения данных)

Внимание: это машинный перевод.

Это руководство охватывает полный цикл интеграции: получение session token, съемка медиа с помощью SDK, отправка полученного контейнера OzCapsula в Oz API Instant, чтение ответа, принятие решения о допуске или отклонении, уменьшение размера ответа и базовая диагностика.

В описании процесса упоминаются:

• Режим съемки – Web SDK (или Mobile SDK) снимает видео для Liveness в браузере или приложении, а бэкенд клиента передает его в Oz API. Результаты съемки не отправляются из SDK напрямую в Oz API: бэкенд клиента выступает посредником.

• OzCapsula – проприетарный зашифрованный бинарный контейнер. SDK упаковывает в него снятые медиаданные и метаданные; Oz API расшифровывает и обрабатывает его. Контейнер защищает снятые данные от изменения на пути от устройства пользователя до Oz API. Контейнер — это непрозрачный зашифрованный blob. Вы не можете декодировать его, просматривать его содержимое или извлекать из него отдельные изображения, кадры или метаданные на стороне клиента. Контейнер необходимо передать на бэкенд в исходном виде. Если вам нужен доступ к снятым изображениям (например, к лучшему кадру), получайте их из ответа Oz API на стороне сервера.

• Instant API – режим Oz API без сохранения данных. Результаты возвращаются сразу в ответе, ничего не сохраняется.

Вместе: SDK снимает медиа и упаковывает их в OzCapsula → ваш бэкенд передает контейнер в Oz API Instant → Oz API синхронно возвращает результат, ничего не сохраняя.

Глоссарий

Несколько терминов, используемых в этом руководстве.

• {{host}} – базовый URL вашего развертывания Oz API. Предоставляется вам при настройке.

• Session token – краткосрочный токен, который привязывает OzCapsula к конкретной сессии съемки и предотвращает повторное использование того же контейнера позже. Обязателен для OzCapsula.

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

• Тип анализа – то, что Oz API выполняет над медиа. API возвращает QUALITY для анализов Liveness и BIOMETRY для анализов Face Matching.

Версии компонентов

Компонент	Минимальная версия
Oz API	6.6.1
Mobile SDK (iOS, Android)	10.0.0
Web SDK	1.9.10

1

Получите session token

OzCapsula требует session token для каждой сессии съемки.

Чтобы включить функциональность session token, сгенерируйте пару ключей JWT. Инструкции по их созданию см. в helm-чарте API Instant: перейдите к readme.md и в разделе Preparation найдите подраздел Create a JWT secret. Получив ключи, создайте папку в вашей установке, поместите ключи туда и укажите этот путь в API_KEYS_DIR (например, API_KEYS_DIR=/opt/oz/api/keys). Это выполняется один раз для установки.

Запросите session token у Oz API Instant. Запрашивайте его перед каждой сессией съемки — как можно ближе к моменту, когда пользователь начинает съемку.

Эндпойнт:

GET {{host}}/api/authorize/session_token

Заголовки:

• Content-Type: application/json

Запрос:

curl -L 'https://{{host}}/api/authorize/session_token' \
  -H 'Content-Type: application/json'

Ответ:

{
  "session_token": "<session_token>"
}

Токен краткосрочный (время жизни по умолчанию: 900 секунд для API Full, 120 секунд для Instant API). Запрашивайте один токен на сессию съемки и сразу же передавайте его в SDK — не кэшируйте и не используйте повторно в разных сессиях.

Механизм авторизации при вызове Oz API зависит от установки; по умолчанию токен доступа в заголовках не требуется. Если в вашем случае он требуется, см. раздел Аутентификация.

2

Съемка и упаковка на устройстве

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

Mobile SDK (iOS, Android)

Запустите анализ с session token. Контейнер возвращается через коллбэк результата.

Android (Kotlin)

// Launch the capture screen
val captureRequest = CaptureRequest(
    listOf(
        AnalysisProfile(
            Analysis.Type.QUALITY,
            listOf(MediaRequest.ActionMedia(OzAction.Blank))
        )
    )
)
val intent = OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)
startActivityForResult(intent, REQUEST_LIVENESS_CONTAINER)

// Obtain the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_LIVENESS_CONTAINER) {
        when (resultCode) {
            OzLivenessResultCode.SUCCESS -> {
                val container = OzLivenessSDK.getContainerFromIntent(data)
                handleContainer(container)
            }
            OzLivenessResultCode.USER_CLOSED_LIVENESS -> { /* user closed the screen */ }
            else -> {
                val errorMessage = OzLivenessSDK.getErrorFromIntent(data)
                /* show error */
            }
        }
    }
}

iOS (Swift)

// Launch the capture screen
let mediaRequest = MediaRequest.action(.selfie)

let profile = AnalysisProfile(
    mediaList: [mediaRequest],
    type: .quality,
    params: [:]
)

let request = CaptureRequest(
    analysisProfileList: [profile],
    cameraPosition: .front
)

let livenessVC = try OZSDK.createMediaCaptureScreen(
    delegate,
    request,
    sessionToken: sessionToken
)

livenessVC.modalPresentationStyle = .fullScreen
parent.present(livenessVC, animated: true)

// Obtain the result
extension YourViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
        // Pass container to Step 5
        handleContainer(container)
    }

    func onError(status: OZVerificationStatus?) {
        // user cancelled, capture failed, etc.
    }
}

Контейнер возвращается как bytearray (Android) или DataContainer (iOS). Передайте его на бэкенд без каких-либо преобразований.

Web SDK

Вызовите OzLiveness.Open() с session token. По завершении съемки SDK вызывает коллбэк on_capture_complete. Контейнер передается вторым аргументом.

OzLiveness.open({
  lang: 'en',
  session_token: session_token,
  action: ['video_selfie_blank'], // request passive liveness video
  on_capture_complete: function(action, ozCapsula) {
    // ozCapsula is a Blob (application/octet-stream)
    // forward it to your backend
  },
  on_error: function (err) { /* handle error */ }
});

Контейнер приходит как Blob с MIME-типом application/octet-stream. Передайте его на бэкенд без каких-либо преобразований.

3

Анализ Liveness: отправьте контейнер в Instant API

Ваш бэкенд передает контейнер в одном синхронном POST-запросе.

Эндпойнт:

POST {{host}}/api/instant/folders/

Заголовки:

• Content-Type: application/octet-stream (обязательно)

Тело запроса: необработанные байты контейнера — без JSON-обертки, без multipart, без base64.

curl -X POST '{{host}}/api/instant/folders/' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'

При успехе: HTTP 201 с JSON-объектом папки, описывающим результат.

При ошибке на уровне контейнера: HTTP 400 (см. раздел «Неуспешные результаты»).

Анализ QUALITY (Liveness) предоставляет лучший кадр. Найдите запись QUALITY в массиве analyses[] и читайте:

$.analyses[*].results_media[*].output_images[*].image_b64

Значение — это JPEG в кодировке base64. Декодируйте его в JPEG.

4

Анализ Biometry (Face Matching) (опционально)

Если сопоставление лиц вам не нужно, пропустите этот шаг и переходите сразу к шагу 5.

Вызовите POST /api/instant/folders/ с вашим эталонным фото и лучшим кадром, полученным из анализа Liveness на шаге 3.

Ключи ваших медиафайлов и соответствующие имена файлов должны совпадать.

Тело запроса:

{
  "media:tags": {
    "UUID_of_reference_photo.jpeg": ["photo_selfie"],
    "best_shot.jpeg": ["photo_selfie"]
  },
  "analyses": [
    { "type": "biometry" }
  ]
}

Ответ будет содержать результат анализа biometry.

5

Прочитайте ответ

Поля верхнего уровня

Поле	Назначение
folder_id	Уникальный идентификатор запроса
resolution_status	Завершена ли обработка: FINISHED или FAILED
system_resolution	Общий результат: SUCCESS, DECLINED или FAILED
resolution_comment	Примечание о разрешении анализа. Полезно при FAILED (перечисляет, какие анализы не прошли)
meta_data	Блок метаданных. Содержит event_session_id — идентификатор сессии, необходимый для соотнесения запроса с сессией пользователя в вашем фронтенде
media	Медиафайлы, отправленные в контейнере
analyses	Массив результатов по каждому анализу

Внутри analyses[]

Поле	Назначение
type	QUALITY для Liveness, BIOMETRY для сопоставления лиц
state	Состояние обработки этого анализа: FINISHED или FAILED
resolution_status	Результат этого анализа: SUCCESS, DECLINED или FAILED
error_code, error_message	Отображаются только при технической ошибке анализа
results_data	Агрегированные значения результата
results_media	Сгенерированные медиаэлементы. Для анализа QUALITY содержит лучший кадр в output_images[] — см. шаг 3
source_media	Входные медиа

Примите решение о допуске или отклонении

Используйте только эти два поля верхнего уровня:

$.resolution_status   // "FINISHED" — анализы завершены; "FAILED" — ошибка при обработке анализа
$.system_resolution   // "SUCCESS", "DECLINED" или "FAILED"

Интерпретация значений system_resolution:

• SUCCESS — все проверки пройдены; пользователь допускается.

• DECLINED — одна или несколько проверок не пройдены; пользователь отклоняется.

• FAILED — системная ошибка не позволила завершить хотя бы один анализ; не следует трактовать как допуск или отклонение (см. раздел «Неуспешные результаты»).

Для получения результатов по каждому анализу отдельно (например, чтобы узнать, прошла ли Liveness, но не прошло сопоставление лиц) читайте $.analyses[*].resolution_status с теми же тремя значениями.

Прочие поля

Ответ также содержит внутренние идентификаторы (group_id, media_association_id), хеши файлов, поля, связанные с оператором (operator_comment, operator_status, is_cleared), и другие системные поля. Для потока интеграции, описанного в этом руководстве, они не нужны.

6

Неуспешные результаты

Недопустимый контейнер – HTTP 400

Когда контейнер не проходит валидацию, Oz API отвечает HTTP 400 и error_message: "Invalid request data". Конкретный error_code указывает на причину:

error_code	Условие
3	Отсутствует payload
4	В контейнере нет медиа
5	Контейнер поврежден
13	В запросе нет контейнера
14	Недопустимый контейнер — любая причина (ошибка расшифровки, подписи, хеша или валидации session_token)

Коды 13 и 14 срабатывают до распаковки контейнера; коды 3, 4, 5 срабатывают после распаковки, когда сам payload не проходит бизнес-валидацию.

Для кода 14 отправьте экземпляр контейнера и error_code в поддержку Oz Forensics — конкретная причина доступна только в серверных логах.

Отклонено – HTTP 201

Контейнер был валиден и анализы выполнились, но хотя бы одна проверка не прошла.

• resolution_status: FINISHED.

• system_resolution: DECLINED.

• resolution_comment: "[]" (неинформативно — причина отклонения неявно содержится в результате по каждому анализу).

• По каждому анализу resolution_status: DECLINED.

Ошибка – HTTP 201

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

• resolution_status: FAILED.

• system_resolution: FAILED.

• resolution_comment — строка с перечислением того, какие анализы не прошли и с каким кодом.

• По каждому анализу state: FAILED, resolution_status: FAILED, заполнены error_code и error_message.