Работа с OZ Mobile SDK в операционной системе «Android»

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

Демо-приложение

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

https://ozforensics.com/ru/demokit

Исходные коды примеров приложений с использованием Oz Liveness SDK расположены в репозитории GitHub:

https://gitlab.com/oz-forensics/oz-liveness-android-sample-java
https://gitlab.com/oz-forensics/oz-liveness-android-sample-kotlin

Добавление функционала SDK в мобильное приложение клиента

Установка OZ Mobile SDK

Для добавления OZ Mobile SDK в проект скопируйте файл ozlivenesssdk.aar в директорию "libs" проекта, а также добавьте включение *.aar в build.gradle приложения.


    dependencies {  
        implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    }

Настройка проекта

Следующие зависимости необходимо добавить в build.gradle приложения:


    dependencies {  
        implementation 'androidx.multidex:multidex:2.0.1'
        implementation 'com.squareup.retrofit2:retrofit:2.6.2'
        implementation 'com.squareup.retrofit2:converter-gson:2.6.2'
        implementation 'com.google.firebase:firebase-core:17.3.0'
        implementation 'com.google.firebase:firebase-ml-vision:24.0.1'
    }  

Для работы SDK также необходимо создать проект Firebase по ссылке https://console.firebase.google.com/ и зарегистрировать там Ваше приложение добавив google-services.json.

Настройки Oz Mobile SDK

Применять настройки рекомендуется при старте приложения.

OzLivenessSDK.baseURL – URL-сервера Oz API, с которым будет общаться SDK

OzLivenessSDK.accessToken - токен доступа к серверу Oz API

OzLivenessSDK.attemptSettings - настройки количества попыток детектирования действия

OzLivenessSDK.allowDebugVisualization - возможность отображения дополнительной debug-информации (нажатием на текст с номером версии СДК)

OzLivenessSDK.logging - настройки логирования

Кастомизация интерфейса Oz Mobile SDK

Кастомизация интерфейса Oz Liveness возможна с использованием класса «OzCustomization» и его подклассов:


    OzLivenessSDK.customization = OzCustomization(
        OzCancelButtonCustomization(R.drawable.ic_arrow),
        OzCenterHintCustomization(16f, Typeface.MONOSPACE, Color.CYAN, 1.3f),
        OzDialogCustomization(R.style.Custom_Dialog_Theme),
        OzFrameCustomization(Color.argb(100, 250,100,100)),
        OzOvalCustomization(35f, Color.YELLOW, Color.MAGENTA)
    )

По умолчанию SDK использует локаль устройства. Локаль можно изменить вызвав «OzLivenessSDK.localizationCode» перед стартом SDK:


    OzLivenessSDK.localizationCode= OzLocalizationCode.RU

Авторизация Oz API

Для авторизации Oz Api и получения access-токена нужно с применением полученных от Вашего менеджера Oz Forensics логина и пароля воспользоваться методом «OzLivenessSDK.login»:


    val loginListener = object: StatusListener { 
        override fun onSuccess(token: String) { 
        //save token
        }
        override fun onError(errorCode: OzException) {}  
    }
    OzLivenessSDK.login(appContext, USER_NAME, PASSWORD, loginListener)  

Или, в случае если access-токен у Вас уже есть, задать URL API и access-токен вручную:


    OzLivenessSDK.baseURL = "https://api.oz-services.ru/" 
    OzLivenessSDK.accessToken = RECEIVED_TOKEN // string

Съёмка видео

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


    val actions = listOf(OzAction.Smile, OzAction.Scan)  
    val intent = OzLivenessSDK.createStartIntent(this,actions )  
    startActivityForResult(intent, REQUEST_CODE)  

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

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


    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
            super.onActivityResult(requestCode, resultCode, data) 
            if (resultCode == REQUEST_CODE) { 
            sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
            sdkErrorString = OzLivenessSDK.getErrorFromIntent(data) } 
        }
    }

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

sdkErrorString – описание ошибок, в случае их возникновения

Отправка медиа-файлов на анализ

Для отправки данных на сервер Oz API и назначения анализа используйте полученный при съёмке объект OzMedia. Вы можете использовать сконструированный SDK объект из примера ниже, создать свой объект или комбинировать оба способа.


    private val statusListener = object: StatusListener<List<OzAnalysisResult>> {
        override fun onStatusChanged(status: String?) {
            //your code for showing status message 
        }  
        override fun onSuccess(result: List) {
            //your code to handle analysis result 
        }
        override fun onError(error: OzException) { }
    }

    OzLivenessSDK.uploadMediaAndAnalyze(applicationContext, sdkMediaResult, statusListener)  

Анализ QUALITY (Liveness) будет назначен на все переданные видео.

Анализ BIOMETRY будет назначен на фото-файлы с тэгами "photo_id_front" и на все видео-файлы.

Анализ DOZUMENTS (Oz Text) будет назначен на фото-файлы с тэгами "photo_id_front" и "photo_id_back".

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

Проведение анализа занимает некоторое время и происходит асинхронно. Проверить статус выполнения анализа и получить результат можно методом «UploadAndAnalyzeStatusListener»:


    val listener = object : StatusListener<List<OzAnalysisResult>> {
        override fun onStatusChanged(status: String?) {
            status?.let { statusSubject?.onNext(it) }
        }

        override fun onSuccess(result: List) {
            it.onSuccess(result)
        }

        override fun onError(error: OzException) {
            if (!it.isDisposed) it.onError(error)
        }
    }
    val cancelable = OzLivenessSDK.uploadMediaAndAnalyze(context, mediaList, listener)

Результат выполнения анализов возвращается в «List»

Получение логов Oz Mobile SDK

В случае, если приложению необходимо получить лог Oz Mobile SDK (например начало\окончание записи и т.п) следует использовать метод «OzLivenessSDK.logging.journalObserver»


    OzLivenessSDK.logging.journalObserver = object : JournalObserver {
        override fun update(event: String) {
            // todo with event string
        }
    }

Прочие методы Oz Mobile SDK

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


    OzLivenessSDK.isLogged(context: Context)  

LogOut:


    OzLivenessSDK.logOut(context: Context)

Работа с серверным Oz API

Retrofit API-интерфейс

SDK содержит интерфейс «IOzForensicsAPI» с описанием сетевых вызовов к АПИ, который можно использовать для создания инстанса Retrofit.

Этот интерфейс использует gson-converter и оперирует классами из пакета «com.ozforensics.liveness.sdk.api.model».

Кроме того в этом интерфейсе определен статический метод для создания инстанса Retrofit-по умолчанию (без логирования, интерцепторов и прочего, таймауты 15 секунд), который будет обращаться к серверу по заданному адресу:


    val service = IOzForensicsAPI.create(URL)

Класс «OzForensicsService»

SDK содержит класс «OzForensicsService», использующий Retrofit-инстанс из «IOzForensicsAPI.create()». Этот класс обертывает сетевые вызовы из Retrofit-интерфейса и учитывает наличие токена. При выполнении запроса auth, автоматически сохраняет для себя токен, кроме того этот класс выполняет сетевые запросы, добавляя необходимую метаинформацию там, где это необходимо (создание папки, выгрузка медиа на анализ), кроме того вызовы методов этого класса асинхронные (используются интерфейс «StatusListener<>»)

Получить экземпляр класса можно следующим образом:


    val service = OzForensicsService(CONTEXT, URL, TOKEN)

Если параметр «TOKEN» передать равным «null», то для выполнения вызовов к апи (кроме auth) необходимо выполнить сначала авторизацию:


    service.auth(EMAIL, PASSWORD, listener)

После удачного запроса будет выполнен «onSuccesCallback», в который будет передан AuthResponse c access-токеном.