Interaction with OZ Mobile SDK in Android

OZ Mobile SDK for Android stands for the Software Developer’s Kit of the Oz Forensics Platform providing seamless integration with customers’ mobile apps for login and biometric identification.

Demo App

Download the demo app latest build:

Sample apps source codes using the Oz Liveness SDK are located in the GitHub repository:

Adding SDK to a project

Add to the build.gradle of the project:

  allprojects {
    repositories {
        maven { url "" }

Add to the build.gradle of the module:

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


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

Oz Mobile SDK settings

We recommend applying these settings when starting the app.

OzLivenessSDK.baseURL - URL of the Oz API server that SDK will interact with

OzLivenessSDK.accessToken - token to access the Oz API server

OzLivenessSDK.attemptSettings - settings for the number of attempts to detect an action

OzLivenessSDK.allowDebugVisualization - possibility to display additional debug information (by clicking the SDK version number)

OzLivenessSDK.logging - logging settings

Customization of the Oz Mobile SDK interface

You can customize the Oz Liveness interface with the help of OzCustomization class and its subclasses:

  OzLivenessSDK.customization = OzCustomization(
    OzCenterHintCustomization(16f, Typeface.MONOSPACE, Color.CYAN, 1.3f),
    OzFrameCustomization(Color.argb(100, 250,100,100)),
    OzOvalCustomization(35f, Color.YELLOW, Color.MAGENTA)

By default, SDK uses the locale of the device. To switch the locale call “OzLivenessSDK.localizationCode” before starting the SDK:

  OzLivenessSDK.localizationCode= OzLocalizationCode.RU

Authorization of the Oz API

To authorize the Oz Api and obtain an access token use method “OzLivenessSDK.login” with login and password provided by your Oz Forensics account manager:

  val loginListener = object: StatusListener < String > {
     override fun onSuccess(token: String) {
       //save token

     override fun onError(errorCode: OzException) {}
  OzLivenessSDK.login(appContext, USER_NAME, PASSWORD, loginListener)

Alternatively, if you already have an access token, specify the API URL and the token manually:

  OzLivenessSDK.baseURL = ""
  OzLivenessSDK.accessToken = RECEIVED_TOKEN // string

Capturing videos

Method “startActivityForResult” is used to start recording:

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

actions – list of user actions while recording video. Possible actions are:

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

To obtain the captured video, method “onActivityResult” is used:

  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 – an object with video capturing results for interactions with Oz API

sdkErrorString – description of errors, if any

Uploading media files to be analyzed

Data to be uploaded and analyzed are stored in object sdkMediaResult, obtained after capturing and recording video. Upload it to the server and initiate required analyses with the use of Oz API. See methods Folder ADD, Folder Media ADD, Analyse ADD, etc.
Analyses are performed asynchronously, their statuses and results can be retrieved with the help of methods Folder SINGLE and Analyse LIST

A simple scenario of interaction with Oz API can be implemented with method uploadMediaAndAnalyze as described below.

  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) analysis will be assigned to all uploaded videos;

BIOMETRY analysis will be assigned to picture files with "photo_id_front" tag and to all video files;

DOCUMENTS (Oz Text) analysis will be assigned to picture files with "photo_id_front" and "photo_id_back” tags.

Obtaining Oz Mobile SDK logs

If your app needs to obtain Oz Mobile SDK logs (like start/end of recording etc.), method “OzLivenessSDK.logging.journalObserver” should be used.

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

Other Oz Mobile SDK methods

Check for the presence of a saved Oz API access token:

  OzLivenessSDK.isLogged(context: Context)


  OzLivenessSDK.logOut(context: Context)

Interactions with server Oz API

Retrofit API

SDK contains IOzForensicsAPI interface describing APO net calls that can be used to create a Retrofit instance.

This interface uses a gson-converter and operates classes from “com.ozforensics.liveness.sdk.api.model” pack.

Apart from this, the interface specifies a static method for creating a default Retrofit instance (without logging, interceptors and the like, with 15 s time-outs). This instance will look for the server at the specified address:

  val service = IOzForensicsAPI.create(URL)

“OzForensicsService” class

SDK includes “OzForensicsService” class that uses a Retrofit instance from “IOzForensicsAPI.create()”. This class wraps in net calls from the Retrofit interface and regards the presence of a token. When an auth request is performed, the token is stored automatically for internal goals. Also required meta data are added where necessary when performing net requests (creating a folder, uploading media data to be analyzed). Method calls of this class are asynchronous (“StatusListener<>” interface is used). You can obtain an instance of this class as follows:

  val service = OzForensicsService(CONTEXT, URL, TOKEN)

If the “TOKEN” parameter value is set to “null”, authorization is required before any API calls can be performed (except auth):

  service.auth(EMAIL, PASSWORD, listener)

After a successful request “onSuccesCallback” is performed so that the access token can be transferred with AuthResponse.