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

Из этой статьи вы узнаете, как интегрировать Oz Liveness Web SDK в клиентское Web-приложение: для съемки видео с лицом и дальнейшей его проверки на сервере.

Преимущества Oz Liveness Web SDK:

• Готовый интерфейс для съемки видео, который легко встроить в приложение клиента.

• Высокое качество видео, которое обеспечивает точность проверки Liveness.

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

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

«Под капотом» Web SDK взаимодействует с OZ API.

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

1. Получите доступ к персональной копии Web Adapter

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

Доменные имена:

1. www.yourbrand.com

2. www.yourbrand2.com

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

• ivan.ivanov@yourcompany.com

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

Логин: ivan.ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web-консоль: https://sandbox.ohio.ozforensics.com

Web Adapter: https://web-sdk.cdn.sandbox.ozforensics.com/your_company_name/

2. Добавьте Web Plugin на вашу страницу

В HTML-коде страницы разместите следующее. web-adapter-url необходимо заменить на полученную от нас ссылку.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Из этой статьи вы узнаете, как интегрировать Oz Liveness Mobile SDK в клиентское мобильное приложение: для съемки видео с лицом и дальнейшей его проверки на сервере.

Oz Liveness Mobile SDK – это:

• Готовый интерфейс для съемки видео, который легко встроить в приложение клиента.

• Высокое качество видео, которое обеспечивает точность проверки Liveness.

«Под капотом» Oz SDK взаимодействует с OZ API.

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

Логин: ivan.ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web-консоль: https://sandbox.ohio.ozforensics.com

Для работы Oz Liveness Mobile SDK нужна лицензия, которая привязывается к bundle_id приложения, например com.yourcompany.yourapp. Тестовую лицензию на месяц вы можете оформить самостоятельно на нашем веб-сайте, если вам требуется лицензия на более длительный срок – свяжитесь с нами.

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

Android

1. Добавьте SDK в проект

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

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

В build.gradle модуля добавьте строки:

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // номер версии можно найти в журнале изменений для Android
}

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в папку res/raw в вашем проекте.

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics))
)

OzLivenessSDK.INSTANCE.init(
        context,
        Collections.singletonList(new LicenseSource.LicenseAssetId(R.raw.forensics)),
        null
);

3. Подключите SDK к Oz API

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

OzLivenessSDK.setApiConnection(
    OzConnection.fromCredentials(host, username, password),
    statusListener(
        { token -> /* token */ },
        { ex -> /* error */ }
    )
)

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromCredentials(host, username, password),
        new StatusListener<String>() {
            @Override
            public void onStatusChanged(@Nullable String s) {}
            @Override
            public void onSuccess(String token) { /* token */ }
            @Override
            public void onError(@NonNull OzException e) { /* error */ }
        }
);

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

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

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

4. Add face recording

Для начала съемки используйте метод startActivityForResult:

val OZ_LIVENESS_REQUEST_CODE = 1
val intent = OzLivenessSDK.createStartIntent(listOf( OzAction.Blank)) startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE)

int OZ_LIVENESS_REQUEST_CODE = 1;
Intent intent = OzLivenessSDK.INSTANCE.createStartIntent(Collections.singletonList(OzAction.Blank));
startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE);

Для получения готового видео используйте onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
            val sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
            val sdkErrorString = OzLivenessSDK.getErrorFromIntent(data)
            if (!sdkMediaResult.isNullOrEmpty()) {
                analyzeMedia(sdkMediaResult)
            } else println(sdkErrorString)
        }
    }

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
        List<OzAbstractMedia> sdkMediaResult = OzLivenessSDK.INSTANCE.getResultFromIntent(data);
        String sdkErrorString = OzLivenessSDK.INSTANCE.getErrorFromIntent(data);
        if (sdkMediaResult != null && !sdkMediaResult.isEmpty()) {
            analyzeMedia(sdkMediaResult);
        } else System.out.println(sdkErrorString);
    }
}

Готовые видео содержатся в объекте sdkMediaResult.

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

Для запуска анализов используйте код ниже. mediaList – массив объектов, полученных из sdkMediaResult или извне (если вы снимали видео без использования нашего SDK).

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList))
        .build()
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                result.forEach { 
                    println(it.resolution.name)
                    println(it.folderId)
                }
            }
            override fun onError(error: OzException) {
                error.printStackTrace()
            }
        })
} 

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    for (OzAnalysisResult result: list) {
                        System.out.println(result.getResolution().name());
                        System.out.println(result.getFolderId());
                    }
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

iOS

1. Добавьте SDK в проект

Установите OZLivenessSDK через CocoaPods. Чтобы встроить SDK в проект Xcode, в Podfile добавьте:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => '<version>' // You can find the version needed in  iOS changelog

2. Инициализируйте SDK

Переименуйте файл лицензии в forensics.license и поместите его в проект.

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

3. Подключите SDK к Oz API

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

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Your code to handle error or token
}

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

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

4. Запустите съемку видео

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

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

В делегате используйте протокол OZLivenessDelegate:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

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

Для запуска анализов используйте AnalysisRequestBuilder. Метод run «под капотом» обратится к Oz API.

let analysisRequest = AnalysisRequestBuilder()
let analysis = Analysis.init(
media: mediaToAnalyze, 
type: .quality, 
mode: .serverBased)
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
analysisRequest.run(
scenarioStateHandler: { state in }, // обработчик шагов сценария
uploadProgressHandler: { (progress) in } // обработчик для загрузки файлов 
) { (analysisResults : [OzAnalysisResult], error) in 
    // получение и обработка анализов 
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

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

В руководстве разработчика вы также найдете инструкции по настройке внешнего вида SDK и список методов SDK как для iOS, так и для Android:

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

Ключевые преимущества Oz API:

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

• Возможность работать и с фото, и с видео

• Асинхронность анализов

• Безопасная аутентификация

• Гибкая настройка уровней доступа

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

Здесь мы приводим пошаговую инструкцию по проведению проверки Liveness для фото или видео лица, которое вы уже сняли с помощью бэкенда Oz.

• Создание папки

• Загрузка медиафайла в папку

• Проверка Liveness

• Получение результатов

Для вашего удобства и повышения точности анализов мы рекомендуем использовать для съемки медиа наши Web или Mobile SDK. Как это сделать, описано здесь:

Чтобы начать, вам понадобятся логин и пароль. Напишите нам, и вы отправим вам всю необходимую информацию, включая ссылки:

Логин: ivan_ivanov@yourcompany.com

Пароль: …

API: https://sandbox.ohio.ozforensics.com

Web Console: https://sandbox.ohio.ozforensics.com

1. Получите токен доступа

В ответе вам придет токен доступа. В дальнейшем его нужно будет указывать в поле X-Forensic-Access-Token.

2. Поместите отдельные фотографии в архивы (для версии 4.0.8 и ниже)

Внимание: если вы используете API версии 5.0.0 или новее, пропустите этот шаг.

3. Загрузите медиафайлы в папку

В поле payload укажите следующие теги:

В случае успеха вернется код 201. В ответе будет идентификатор папки folder_id – он понадобится в дальнейшем.

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

Метод вернет analyse_id, который потребуется на следующем шаге.

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

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

• количественные – в results_media[0].results_data.confidence_spoofing. confidence_spoofing; они варьируются от 0.0 до 1.0, где 0.0 означает, что на фото или видео реальный человек, а 1.0 – что система обнаружила спуфинг-атаку.

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