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

Use this link to download the current build of the demo app:

https://ozforensics.com/demokit

Source codes of app samples using Oz Liveness SDK are provided in the GitHub repository:

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

Adding SDK Functionality to Customer's Mobile Application

Installation of OZ Mobile SDK

To add OZ Mobile SDK to a project copy file ozlivenesssdk.aar to the libs-directory of such project and add *.aar in app build.gradle.


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

Setting Up a Project

Following dependencies should be added to app 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'
    }  

In order to use SDK you should also create a Firebase project at https://console.firebase.google.com/ and register your app there by adding google-services.json.

Oz Mobile SDK Settings

It is recommended to apply settings at launching the app.

OzLivenessSDK.baseURL – URL of the Oz API server that SDK will communicate with SDK

OzLivenessSDK.accessToken - Oz API server access token

OzLivenessSDK.attemptSettings - for the number of action detection attempts

OzLivenessSDK.allowDebugVisualization - display of additional debugging information (by pressing the text with SDK version number)

OzLivenessSDK.logging - logging settings

Customization of the Oz Mobile SDK Interface

Oz Liveness interface can be customized with the use if class “OzCustomization” and its subclasses:


    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 uses the locale of the device by default. You can call “OzLivenessSDK.localizationCode” before launching SDK to adjust the locale:


    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 manager:


    val loginListener = object: StatusListener { 
        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, you can specify the API URL and access token manually:


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

Recording Videos

To start video recording, method “startActivityForResult”: is used:


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

actions – list of user’s actions while recording videos.

To obtain the video recording results, 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 – object with the results of recording video for subsequent use in interactions with Oz API

sdkErrorString – description of errors, if any

Submitting Media Files to Be Analyzed

To submit data to Oz API server and assign an analysis use the OzMedia object created at the video recording. Use the developed SDK object from the following sample or create an own object or combine the both ways.


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

BIOMETRY analysis will be assigned to picture files with “photo_id_front” tag and all video files

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

Receiving Analysis Results

The process of file analysis takes time and is asynchronous. You can check the analysis status and receive a result with method “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)

The result of analyses is returned in «List»

Obtaining Oz Mobile SDK Logs

If the app requires Oz Mobile SDK logs (eg.: start/end of recording etc.), method “OzLivenessSDK.logging.journalObserver” is used.


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

Other Oz Mobile SDK Methods

Checking availability of a saved Oz API access token:


    OzLivenessSDK.isLogged(context: Context)  

LogOut:


    OzLivenessSDK.logOut(context: Context)

Interaction with Oz API on a Server

Retrofit API Interface

SDK includes IOzForensicsAPI with description of network calls to API. This interface can be used to generate a Retrofit instance.

It uses gson-converter and operates classes from “com.ozforensics.liveness.sdk.api.model” package.

Also it has a static method to generate a default Retrofit instance (no logging, interceptors etc.; with 15 second timeouts) that will access server at the specified address:


    val service = IOzForensicsAPI.create(URL)

«OzForensicsService» Class

SDK includes class “OzForensicsService” that uses a Retrofit instance from “IOzForensicsAPI.create()”. This class wraps around network calls from the Retrofit interface and takes into account whether a token is present. When processing an auth request, it saves the token automatically for own needs. Also this class processes network requests, adding required meta information data where appropriate (creating a folder, downloading media files to be analyzed). Asynchronous method calls are used for this class (“StatusListener<>” interface).

Code retrieving an instance of this class:


    val service = OzForensicsService(CONTEXT, URL, TOKEN)

If the parameter “TOKEN” becomes value “null”, pre-authorization will be required to process calls to the API (except auth):


    service.auth(EMAIL, PASSWORD, listener)

After a successful request “onSuccesCallback” is generated, and AuthResponse with the access token is transferred.