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

Установка

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

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

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

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

unzip license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json.zip

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

Пример

scp -i ~/ozforensics/keys/id_rsa-test-hostname-vm license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json user@hostname:/opt/oz/web-sdk

• -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. Замените файл лицензии.

Пример

ssh user@hostname -i ~/ozforensics/keys/id_rsa-test-hostname-vm sudo cp -v /opt/oz/web-sdk/license.license.0000aaaa-00aa-00aa-00aa-00000aaaaa.WebSDK_your_website.2022-10-11.json /opt/oz/web-sdk/license.json

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

Пример

ssh user@hostname -i ~/ozforensics/keys/id_rsa-test-hostname-vm sudo docker restart web-sdk

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

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

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

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

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

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

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

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

mkdir /opt/oz
cd /opt/oz
tar xzf oz-lic.tar.gz

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

./LexFloatServer -p product.dat -c config.yml -i --service-name ozlic

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этом разделе описано содержимое файла конфигурации /core/app_config.json.

• use_for_liveness – опция применяется при использовании WebSDK операторами банка для съемки клиентов. Если use_for_liveness = true, при съемке лица на мобильных устройствах выбирается тыловая камера, на десктопе отключается флип; отключается обводка овала;

• preinit – параметр включает предварительную загрузку библиотек и инициализацию, уменьшая время использования plugin. Параметр необязательный, значение по умолчанию off – загрузка скриптов и инициализация происходит после открытия plugin и вызова функции OzLiveness.open(). В таком режиме plugin не создает нагрузки на сайт (приложение), на котором он установлен, но сам plugin может открываться долго из-за описанных выше процессов. Значение script – предварительная загрузка только библиотек плагина. Значение full – предварительная загрузка библиотек и инициализация процесса определения лица.

• architecture – выбор архитектуры, в которой используется WebSDK. Параметр необязательный, значение по умолчанию normal.

  • normal для включения полной версии Oz API;

  • lite для использования API Lite;

  • capture – режим для работы с бэкэндом клиента напрямую. В этом случае возможно распространение Oz Liveness Web Plugin только через статические файлы, без адаптера (работает с версии 0.7.4);

• api_url – адрес сервера Oz API, текстовый параметр;

• api_token – токен для доступа к Oz API, текстовый параметр;

• api_use_token – параметр, определяющий источник получения системой токена для доступа к Oz API. Возможные значения = config, client.

  • Если установлено значение client, то токен для доступа к Oz API ожидается от JS-плагина;

  • Если установлено значение config, то токен берется из параметра api_token файла /core/app_config.json.

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

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

• actions_default_importance – возможность при запуске анализа переопределить массив действий из WEB-плагина. Возможные значения = true, false;

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

  • Если установлено false, то адаптер будет использовать массив действий, переданный из браузера методом open(options).

• actions_default – массив действий. Доступные параметры:

  • video_count – количество передаваемых видеофайлов, числовой параметр;

  • photo_front – наличие фронтальной страницы документа. Возможные значения = true, false;

  • photo_back – наличие оборотной страницы документа. Возможные значения = true, false.

• analyses – блок настройки запуска анализов. Доступные параметры:

  • quality – запуск анализа Oz Liveness. Возможные значения = true, false;

  • biometry – запуск анализа Oz Biometry. Возможные значения = true, false;

  • documents – запуск анализа Oz Text. Возможные значения = true, false;

  • collection_ids (с версии 1.4.0) – массив идентификаторов коллекций для анализа по черному списку.

• extract_best_shot – параметр, определяющий необходимость добавления в результат анализа прямой ссылки на лучший кадр, извлеченный из видео. Возможные значения = true, false. Если установлено true, в ответе в output_images (results_media) будет ссылка на извлеченное изображение;

• result_mode – параметр, определяющий содержание ответа сервера с результатами проверки. Возможные значения:

  • safe – возвращается только состояние анализов (завершены или еще нет);

  • status – возвращаются результаты выполнения анализов;

  • folder – то же самое, что status, но дополнительно возвращается folder_id;

  • full (будет отключен в ближайших релизах) – возвращается полная информация, включая чувствительные данные.

• result_codes – блок кодов ответа с комментариями.

• delete_old_sessions – если установлено true, старые сессии удаляются.

• delete_old_sessions_offset_minutes – если установлено, старые сессии удаляются с соответствующим смещением в минутах.

• video_required_actions_list – массив обязательных действий, которые снимающему нужно воспроизвести. См. Active Liveness.

"video_required_actions_list":
[
    "video_selfie_smile"
],

• save_lossless_frame– если true, исходный кадр сохраняется без сжатия.

• video_file_format – выбор формата видео, которое отправляется на api. Возможные значения – zip (рекомендуется), mov (менее безопасный вариант). Чтобы получить видео в MP4, воспользуйтесь инструкцией здесь.

• debug (с версии 1.1.0) – при значении true дает возможность открыть страницу /debug.php, на которой размещена информация о текущих конфигурации и лицензии.

• load_3d_mask (с версии 1.2.1) – если установлено true, загружает модели для обработки видео, снятого с помощью 3D-маски. Значение по умолчанию – false; в этом случае модель не подгружается, и 3D-маску использовать нельзя (параметр enable_3d_mask игнорируется).

• enable_3d_mask (с версии 1.2.1) – включает использование 3D-маски при съемке вместо овала. Параметр работает только в случае load_3d_mask= true; значение по умолчанию – false.

• master_license_signature (с версии 1.3.1) – подпись мастер-лицензии; по умолчанию null.

• results_polling_interval (с версии 1.4.0) – интервал опроса для получения результатов анализов, мс; значение по умолчанию — 1000.

• get_user_media_timeout (с версии 1.5.0) – определяет время, по истечении которого отобразится подсказка о том, как получить доступ к камере, если к тому моменту доступ не был получен; default_default для всех браузеров и android_facebook для Facebook браузеров.

"get_user_media_timeout": {
        "default_default": 40,
        "android_facebook": 5
    }

• disable_adapter_errors_on_screen (с версии 1.5.0) – выключает отображение ошибок в модальных окнах, оставляя возможность их просмотра только в коллбэке on_error. Значение по умолчанию – False.

• auth (с версии 1.7.14) – указывает, используется ли авторизация, и если да, то каким способом:

  • true (по умолчанию) – включена авторизация на базе генерируемого ключа доступа;

  • user:pass – включена авторизация на базе логина и пароля;

  • false – авторизация выключена.

Некоторые параметры файла конфигурации можно переопределять с помощью переменных окружения. В некоторых случаях это позволяет обойтись без редактирования файла конфигурации, например при использовании 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}

Разделы настроек

В зависимости от типа инсталляции (через установщик или с помощью наших инженеров) настройки могут храниться в:

• /opt/gateway/configs на хосте или внутри Docker-контейнера oz-api

• /var/lib/docker/volumes/api_oz-api-config-vol/_data в случае стационарного установщика.

Основной файл настроек – config.py

Подключение к Postgres

DB_USER = 'имя пользователя'
DB_HOST = 'адрес сервера Postgres'
DB_PASS = 'пароль пользователя'
DB_NAME = 'название базы'

Путь к медиафайлам

Все входящие медиафайлы сохраняются в локальную папку, примонтированную к одному из мест в зависимости от установки:

• /opt/gateway/static на хосте или в Docker-контейнере

• /var/lib/docker/volumes/api_oz-api-static-vol/_data - в случае стационарного установщика

• любой указанный заранее путь

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

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

PORT = 443
SCHEME = 'https'
HOST = 'api.globalbank.com'

Связка с Oz Bio / Liveness

OZ_SERVICE_TFSS_HOST = 'http://bio-server-name:8501/v1/'

Тайминги и ограничения

# количество попыток провести анализ при отказе Oz Bio
OZ_CELERY_RETRY_MAX_COUNT = 7
# промежуток между попытками
OZ_CELERY_RETRY_STEP = 30
# максимальное время ожидания одного анализа
OZ_ANALYSE_PROCESSING_EXPIRE_TIMEOUT = 15 * 60  # 15 минут
# максимальное время ожидания анализа API
OZ_ANALYSE_DELIVERY_EXPIRE_TIMEOUT = 60 * 60  # 1 час
# частота проверки просроченности анализа
OZ_ANALYSE_EXPIRE_BEAT_PERIOD = 1 * 60  # каждую минуту

# максимальное количество прикрепленных медиа
OZ_ATTACHMENT_MAX_COUNT = 10
# максимальный размер одного медиа
OZ_ATTACHMENT_MAX_SIZE = 10 * 1024 * 1024  # 10Mb

# количество секунд до истечения авторизационного токена
OZ_SESSION_TTL = 60 * 15  # 15 мин
# количество секунд до истечения сервисного токена
OZ_SESSION_LONGLIVE_TTL = 60 * 60 * 24 * 365 * 5  # 5 лет

# максимальный размер миниатюры в байтах
OZ_IMAGE_SIZE_THUMBNAIL = 300
# максимальная продолжительность видео в секундах
OZ_VIDEO_DURATION_MAX = 30

• WA_CORS_ORIGINS – от каких источников принимать запросы. Значение по умолчанию отсутствует. Если переменная не задана, то CORS headers отключены, т.е. внутри контейнера Web SDK никакие cors headers не будут добавлены!

• WA_CORS_METHODS(необязательно) – Методы HTTP, которые могут использоваться. Если значение переменной не задано, она принимает значение по умолчанию: 'GET, POST, OPTIONS'. Если переменная не указана, можно использовать все методы.

• WA_CORS_HEADERS(необязательно) – Заголовки HTTP, которые могут использоваться. Если значение переменной не задано, она принимает значение по умолчанию: 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,traceparent,esid'. Если переменная не указана, можно использовать все заголовки.

Пример настройки CORS headers через переменные окружения:

docker run -d -p 80:80 \
-e WA_CORS_ORIGINS='*' \
-e WA_CORS_METHODS='GET, POST, OPTIONS' \
-e WA_CORS_HEADERS=DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,traceparent,esid \
ozforensics/oz-webliveness:{tag}

Настройка 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.

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

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