Для запуска окна плагина следует воспользоваться методом open(options). Параметры:

• options – объект с настройками:

  • token – (опционально) токен авторизации;

  • license – объект с информацией о лицензии;

  • licenseUrl – строка, содержащая путь к файлу лицензии;

  • lang – строка с идентификатором одного из подключенных языковых пакетов;

  • meta – объект, ключи которого являются названиями метаполей, а значения – их строковыми значениями. Метаданные передаются в Oz API и могут быть использованы для получения результатов анализа или поиска;

  • params – объект с идентификаторами и значениями дополнительных параметров:

    • extract_best_shot: true/false – запуск выбора лучшего кадра в анализе Quality;

  • action – массив строк с идентификаторами действий, по которым будет проводиться проверка. Доступные действия:

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

    • photo_id_back – фото обратной стороны документа;

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

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

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

    • video_selfie_high – поднятие головы вверх;

    • video_selfie_smile – улыбка;

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

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

    • video_selfie_blank – отсутствие действия, простое селфи.

    • video_selfie_best – специальное действие, которое извлекает из видео лучший кадр и выполняет анализ по нему вместо целого видео.

  • overlay_options – параметры отображения шаблона документа:

    • show_document_pattern: true/false – по умолчанию true, отображает картинку-шаблон, при значении false остается только прямоугольная рамка;

  • on_submit – callback-функция без аргументов, вызываемая после отправки пользовательских данных на сервер (не применяется в режиме capture).

  • on_capture_complete – callback-функция с одним аргументом, вызываемая по завершении съемки и возвращающая информацию о снятом видео. Пример возвращаемого объекта показан здесь.

  • on_complete – callback-функция с одним аргументом, вызываемая после окончания проверки и возвращающая результат анализа (не применяется в режиме capture). Вид результата зависит от параметра настройки Web Adapter result_mode. Описание результата здесь.

  • on_result – callback-функция с одним аргументом, вызываемая раз в несколько секунд в процессе анализа и возвращающая промежуточный результат (не применяется в режиме capture). Вид результата зависит от параметра настройки Web Adapter result_mode. Описание результата здесь.

  • on_error – callback-функция с одним аргументом, вызываемая при ошибке во время съемки и возвращающая информацию об ошибке: код ошибки, сообщение, идентификатор телеметрии для журналирования.

  • on_close – callback-функция без аргументов, вызываемая по окончании проверки после закрытия окна плагина, как ручного, так и автоматического.

  • style – раздел для настройки интерфейса.

  • device_id – (опционально) идентификатор используемой камеры.

  • cameraFacingMode (добавлено в 1.4.0) – параметр, определяющий, какую камеру использовать; возможные значения: user (передняя камера), environment (задняя камера). Этот параметр работает только в том случае, когда для параметра use_for_liveness в файле конфигурации Web Adapter не установлено значение. Если use_for_liveness установлено любое значение, cameraFacingMode игнорируется.

  • disable_adaptive_aspect_ratio (добавлено в 1.5.0) – выключает автоматическую подстройку соотношения сторон видео к соотношению сторон окна. Значение по умолчанию – False, при стандартных настройках видео подстраивается под ближайшее соотношение из списка: 4:3, 3:4, 16:9, or 9:16. Обратите внимание: для съемки видео на смартфонах нужна портретная ориентация.

  • get_user_media_timeout (добавлено в 1.5.0) – когда SDK не может получить доступ к камере, по истечении этого таймаута появится подсказка, как решить проблему. Значение по умолчанию – 40000 (мс).

Пример:

OzLiveness.open({
    lang: 'en',
    action: [
        'video_selfie_blank',
    ],
    meta: { // если нужно, добавьте метаданные для папки
        'transaction_id': 'your unique transaction identifier', // идентификатор транзакции для поиска через Oz API
        'client_id': 'your client_id',
        'meta_key': 'meta_value',
    },
    on_result: function (result) {
        console.log('on_result', result);
    },
    on_complete: function (result) {
        console.log('on_complete', result);
    },
    on_close: function () {
        console.log('on_close');
    },
    on_capture_complete: function (result) {
        console.log('on_capture_complete', result);
    }
});

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

Safe

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

{
 "state": "processing"
}

или

{
 "state": "finished"
}

Status

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

{
 "state": "processing",
 "analyses": {
   "quality": {
     "state": "processing",
     "resolution": ""
   }
 }
}

или

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

Folder

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

{
 "state": "processing",
 "folder_id": "your_folder_id",
 "analyses": {
   "quality": {
     "state": "processing",
     "resolution": ""
   }
 }
}

Full

В случае, когда result_mode установлен на full, вернется:

• пока анализ выполняется – ответ, аналогичный ответу при значении status (в процессе обработки), или

• полная информация об анализах:

  • все, что вы могли видеть при значении folder;

  • временные метки;

  • метаданные;

  • идентификаторы анализов, компании, группы анализов;

  • пороги;

  • информация о медиафайлах;

  • и так далее.

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

В случае, когда result_mode установлен на full, вернется полная информация об анализах:

• все, что вы могли видеть при значении folder;

• временные метки;

• метаданные;

• идентификаторы анализов, компании, группы анализов;

• пороги;

• информация о медиафайлах;

• и так далее.

1. Обзор

Режим capture работает следующим образом:

1. Oz Web SDK снимает видео и передает его вашему web-приложению в виде последовательности кадров.

2. Web-приложение вызывает ваш бэкэнд и передает в него архив с кадрами.

3. После обработки видео ваш бэкэнд вызывает Oz API для выполнения анализов, после чего получает их результаты.

4. Ваш бэкэнд передает результаты обратно в web-приложение (опционально).

2. Реализация

На стороне сервера необходимо сконфигурировать Web SDK для работы в режиме capture: установить параметру architecture в файле app_config.json значение capture.

В вашем web-приложении добавьте callback-функцию для обработки кадров при открытии плагина Web SDK:

OZLiveness.open({
  ... // другие параметры
  on_capture_complete: function(result) {
         // Код для обработки кадров / отправки его через ваш API, шаг 2 на схеме
  }
})

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

Виртуальная камера не обнаружена

{
	"action": <action>,
	"best_frame": <bestframe>,
	"best_frame_png": <bestframe_png>,
	"best_frame_bounding_box": {
		"left": <bestframe_bb_left>,
		"top": <bestframe_bb_top>,
		"right": <bestframe_bb_right>,
		"bottom": <bestframe_bb_bottom>
		},
	"best_frame_landmarks": {
		"left_eye": [bestframe_x_left_eye, bestframe_y_left_eye],
		"right_eye": [bestframe_x_right_eye, bestframe_y_right_eye],
		"nose_base": [bestframe_x_nose_base, bestframe_y_nose_base],
		"mouth_bottom": [bestframe_x_mouth_bottom, bestframe_y_mouth_bottom],
		"left_ear": [bestframe_x_left_ear, bestframe_y_left_ear],
		"right_ear": [bestframe_x_right_ear, bestframe_y_right_ear]
		},
	"frame_list": [<frame1>, <frame2>],
	"frame_bounding_box_list": [
		{
		"left": <frame1_bb_left>,
		"top": <frame1_bb_top>,
		"right": <frame1_bb_right>,
		"bottom": <frame1_bb_bottom>
		},
		{
		"left": <frame2_bb_left>,
		"top": <frame2_bb_top>,
		"right": <frame2_bb_right>,
		"bottom": <frame2_bb_bottom>
		},
	],
	"frame_landmarks": [
		{
		"left_eye": [frame1_x_left_eye, frame1_y_left_eye],
		"right_eye": [frame1_x_right_eye, frame1_y_right_eye],
		"nose_base": [frame1_x_nose_base, frame1_y_nose_base],
		"mouth_bottom": [frame1_x_mouth_bottom, frame1_y_mouth_bottom],
		"left_ear": [frame1_x_left_ear, frame1_y_left_ear],
		"right_ear": [frame1_x_right_ear, frame1_y_right_ear]
		},
		{
		"left_eye": [frame2_x_left_eye, frame2_y_left_eye],
		"right_eye": [frame2_x_right_eye, frame2_y_right_eye],
		"nose_base": [frame2_x_nose_base, frame2_y_nose_base],
		"mouth_bottom": [frame2_x_mouth_bottom, frame2_y_mouth_bottom],
		"left_ear": [frame2_x_left_ear, frame2_y_left_ear],
		"right_ear": [frame2_x_right_ear, frame2_y_right_ear]
		}
	],
"from_virtual_camera": null,
"additional_info": <additional_info>
}

Виртуальная камера обнаружена

{
	"action": <action>,
	"best_frame": null,
	"best_frame_png": null,
	"best_frame_bounding_box": null,
	"best_frame_landmarks": null
	"frame_list": null,
	"frame_bounding_box_list": null,
	"frame_landmarks": null,
	"from_virtual_camera": {
	"additional_info": <additional_info>,
		"best_frame": <bestframe>,
		"best_frame_png": <best_frame_png>,
		"best_frame_bounding_box": {
			"left": <bestframe_bb_left>,
			"top": <bestframe_bb_top>,
			"right": <bestframe_bb_right>,
			"bottom": <bestframe_bb_bottom>
			},
		"best_frame_landmarks": {
			"left_eye": [bestframe_x_left_eye, bestframe_y_left_eye],
			"right_eye": [bestframe_x_right_eye, bestframe_y_right_eye],
			"nose_base": [bestframe_x_nose_base, bestframe_y_nose_base],
			"mouth_bottom": [bestframe_x_mouth_bottom, bestframe_y_mouth_bottom],
			"left_ear": [bestframe_x_left_ear, bestframe_y_left_ear],
			"right_ear": [bestframe_x_right_ear, bestframe_y_right_ear]
			},
		"frame_list": [<frame1>, <frame2>],
		"frame_bounding_box_list": [
			{
			"left": <frame1_bb_left>,
			"top": <frame1_bb_top>,
			"right": <frame1_bb_right>,
			"bottom": <frame1_bb_bottom>
			},
			{
			"left": <frame2_bb_left>,
			"top": <frame2_bb_top>,
			"right": <frame2_bb_right>,
			"bottom": <frame2_bb_bottom>
			},
			],
		"frame_landmarks": [
			{
			"left_eye": [frame1_x_left_eye, frame1_y_left_eye],
			"right_eye": [frame1_x_right_eye, frame1_y_right_eye],
			"nose_base": [frame1_x_nose_base, frame1_y_nose_base],
			"mouth_bottom": [frame1_x_mouth_bottom, frame1_y_mouth_bottom],
			"left_ear": [frame1_x_left_ear, frame1_y_left_ear],
			"right_ear": [frame1_x_right_ear, frame1_y_right_ear]
			},
			{
			"left_eye": [frame2_x_left_eye, frame2_y_left_eye],
			"right_eye": [frame2_x_right_eye, frame2_y_right_eye],
			"nose_base": [frame2_x_nose_base, frame2_y_nose_base],
			"mouth_bottom": [frame2_x_mouth_bottom, frame2_y_mouth_bottom],
			"left_ear": [frame2_x_left_ear, frame2_y_left_ear],
			"right_ear": [frame2_x_right_ear, frame2_y_right_ear]
			}
		]
	}
}

Список переменных с их значениями приведен ниже.

Обратите внимание:

• Видео, полученное через Oz Web SDK, – это последовательность кадров. Чтобы отправить его Oz API, поместите кадры в ZIP-архив, затем используйте метод POST {{host}}/api/folders (пройдите по ссылке для ознакомления с коллекцией Postman).

• Вы можете получить из папки видео в формате MP4 video: вызовите метод /api/folders/{{folder_id}}, указав идентификатор папки. В JSON-ответе найдите preview_url в source_media. В preview_url содержится ссылка на видео. Из плагина получить MP4-видео нельзя (только в виде последовательности кадров).

• При использовании архитектуры capture также необходимо добавить в запрос POST {{host}}/api/folders дополнительное поле additional_info. Оно нужно для сбора информации о среде клиента. Пример заполнения тела запроса:

"VIDEO_FILE_KEY": VIDEO_FILE_ZIP_BINARY
"payload": "{
        "media:meta_data": {
           "VIDEO_FILE_KEY": {
              "additional_info": <additional_info>
              }
           }
}"

• Для передачи в Oz API используйте данные без кодирования в base64.