Работа с 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

Добавление SDK в проект

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


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

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


  dependencies {
    implementation 'com.ozforensics.liveness:sdk:VERSION'
  }

и:


  android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
  }

Настройки 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 < String > {
     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 – перечень действий пользователя при записи видео. Возможные действия:

  • OzAction.Smile
  • OzAction.ZoomIn
  • OzAction.ZoomOut
  • OzAction.EyeBlink
  • OzAction.HeadUp
  • OzAction.HeadDown
  • OzAction.HeadLeft
  • OzAction.HeadRight
  • OzAction.Scan
  • OzAction.Blank

Для получения результатов записи видео используется метод «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 – описание ошибок, в случае их возникновения

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

Данные для отправки на анализ находятся в объекте sdkMediaResult, полученном после съемки и записи видео. Загрузите их на сервер и инициируйте запуск необходимых анализы с помощью Oz API. См. методы Folder ADD, Folder Media ADD, Analyse ADD и другие.
Анализы проводятся асинхронно, их статус и результаты можно получить с помощью методов Folder SINGLE или Analyse LIST

Для простого сценария взаимодействия с Oz API можно использовать метод uploadMediaAndAnalyze как описано ниже.


  private val statusListener = object: StatusListener < List < OzAnalysisResult > > {
    override fun onStatusChanged(status: String?) {
      //your code for showing status message
    }

    override fun onSuccess(result: List < OzAnalysisResult > ) {
      //your code to handle analysis result
    }

    override fun onError(error: OzException) {
      //your code to handle analysis error
    }
  }

  OzLivenessSDK.uploadMediaAndAnalyze(applicationContext, sdkMediaResult, statusListener)

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

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

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

Получение логов 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-токеном.