Master license is the offline license that allows using Mobile SDKs with any bundle_id, unlike the regular licenses. To get a master license, create a pair of keys as shown below. Email us the public key, and we will email you the master license shortly after that. Your application needs to sign its bundle_id with the private key, and the Mobile SDK checks the signature using the public key from the master license. Master licenses are time-limited.

Generating Keys

This section describes the process of creating your private and public keys.

Creating a Private Key

To create a private key, run the commands below one by one.

openssl genpkey -algorithm RSA -outform DER -out privateKey.der -pkeyopt rsa_keygen_bits:2048
# for MacOS
base64 -i privateKey.der -o privateKey.txt
# for Linux 
base64 -w 0 privateKey.der > privateKey.txt

You will get these files:

• privateKey.der is a private .der key;

• privateKey.txt is privateKey.der encoded by base64. This key containing will be used as the host app bundle_id signature.

File examples:

The OpenSSL command specification: https://www.openssl.org/docs/man1.1.1/man1/openssl-pkcs8.html

Creating a Public Key

To create a public key, run this command.

openssl rsa -pubout -in privateKey.der -out publicKey.pub

You will get the public key file: publicKey.pub. To get a license, please email us this file. We will email you the license.

File example:

SDK Integration

SDK initialization:

fun init(
    context: Context,
    licenseSources: List<LicenseSource>,
    masterLicenseSignature: String,
    statusListener: StatusListener<LicensePayload>? = null,
)

Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id using the private key.

Signature creation example:

private fun getMasterSignature(): String {
    Security.insertProviderAt(org.spongycastle.jce.provider.BouncyCastleProvider(), 1)

    val privateKeyBase64String = "the string copied from the privateKey.txt file"
    // with key example:
    // val privateKeyBase64String = "MIIEpAIBAAKCAQEAxnpv02nNR34uNS0yLRK1o7Za2hs4Rr0s1V1/e1JZpCaK8o5/3uGV+qiaTbKqU6x1tTrlXwE2BRzZJLLQdTfBL/rzqVLQC/n+kAmvsqtHMTUqKquSybSTY/zAxqHF3Fk59Cqisr/KQamPh2tmg3Gu61rr9gU1rOglnuqt7FioNMCMvjW7ciPv+jiawLxaPrzNiApLqHVN+xCFh6LLb4YlGRaNUXlOgnoLGWSQEsLwBZFkDJDSLTJheNVn9oa3PXg4OIlJIPlYVKzIDDcSTNKdzM6opkS5d+86yjI1aTKEH3Zs64+QoEuoDfXUxS3TOUFx8P+wfjOR5tYAT+7TRN4ocwIDAQABAoIBAATWJPV05ZCxbXTURh29D/oOToZ0FVn78CS+44Vgy1hprAcfG9SVkK8L/r6X9PiXAkNJTR+Uivly64Oua8//bNC7f8aHgxRXojFmWwayj8iOMBncFnad1N2h4hy1AnpNHlFp3I8Yh1g0RpAZOOVJFucbTxaup9Ev0wLdWyGgQ3ENmRXAyLU5iUDwUSXg59RCBFKcmsMT2GmmJt1BU4P3lL9KVyLBktqeDWR/l5K5y8pPo6K7m9NaOkynpZo+mHVoOTCtmTj5TC/MH9YRHlF15VxQgBbZXuBPxlYoQCsMDEcZlMBWNw3cNR6VBmGiwHIc/tzSHZVsbY0VRCYEbxhCBZkCgYEA+Uz0VYKnIWViQF2Na6LFuqlfljZlkOvdpU4puYTCdlfpKNT3txYzO0T00HHY9YG9k1AW78YxQwsopOXDCmCqMoRqlbn1SBe6v49pVB85fPYU2+L+lftpPlx6Wa0xcgzwOBZonHb4kvp1tWhUH+B5t27gnvRz/rx5jV2EfmWinycCgYEAy8/aklZcgoXWf93N/0EZcfzQo90LfftkKonpzEyxSzqCw7B9fHY68q/j9HoP4xgJXUKbx1Fa8Wccc0DSoXsSiQFrLhnT8pE2s1ZWvPaUqyT5iOZOW6R+giFSLPWEdwm6+BeFoPQQFHf8XH3Z2QoAepPrEPiDoGN1GSIXcCwoe9UCgYEAgoKj4uQsJJKT1ghj0bZ79xVWQigmEbE47qI1u7Zhq1yoZkTfjcykc2HNHBaNszEBks45w7qo7WU5GOJjsdobH6kst0eLvfsWO9STGoPiL6YQE3EJQHFGjmwRbUL7AK7/Tw2EJG0wApn150s/xxRYBAyasPxegTwgEj6j7xu7/78CgYEAxbkI52zG5I0o0fWBcf9ayx2j30SDcJ3gx+/xlBRW74986pGeu48LkwMWV8fO/9YCx6nl7JC9dHI+xIT/kk8OZUGuFBRUbP95nLPHBB0Hj50YRDqBjCBh5qaizSEGeGFFNIfFSKddri3U8nnZTNiKLGCx7E3bjE7QfCh5qoX8ZF0CgYAtsEPTNKWZKA23qTFI+XAg/cVZpbSjvbHDSE8QB6X8iaKJFXbmIC0LV5tQO/KT4sK8g40m2N9JWUnaryTiXClaUGU3KnSlBdkIA+I77VvMKMGSg+uf4OdfJvvcs4hZTqZRdTm3dez8rsUdiW1cX/iI/dJxF4964YIFR65wL+SoRg=="
    val sig = Signature.getInstance("SHA512WithRSA")
    val keySpec = PKCS8EncodedKeySpec(Base64.decode(privateKeyBase64String, Base64.DEFAULT))
    val keyFactory = KeyFactory.getInstance("RSA")
    sig.initSign(keyFactory.generatePrivate(keySpec))
    sig.update(packageName.toByteArray(Charsets.UTF_8))
    return Base64.encodeToString(sig.sign(), Base64.DEFAULT).replace("\n", "")
}

KohJ1rsUgLMzZHpHGAZDK2efHPnMj9tw9VIedBLvyZt0B2JH3SWfJLJ8X6JNz3bR2sce6PR2wdEIFln0r1pUnD+6WBCgexKIHAv7esiRVQZoZOEANDBwDvJVv73H/0qL2LGlhxKzbBg5CxGPClTBQdLo1P+7HsTXHHG/Hf6m3rdu1OUeGXVPoaS2NzE8kiRH6gb8Nhr7PBLTUeMKTeLoiX13hvwjOqhV1ANhgS97T4hC2+ZilZt4RektgRY/+fGmWnOqErNeYuz/WSInfaJS0YEWhJW3gXKPjdCzNGIBIqbxaFSjU46wu/alh2+tBRFnrYFl1dRQVcTlW0VwwZHcug==

Pass the signature as the masterLicenseSignature parameter during the SDK initialization.

If the signature is invalid, the initialization continues as usual: the SDK checks the list of bundle_id included into the license, like it does it by default without a master license.

Add the following URL to the build.gradle of the project:

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

Add this to the build.gradle of the module (VERSION is the version you need to implement. Please refer to Changelog):

for the server-based version only

Please note: this is the default version.

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

for both server-based and on-device versions

Please note: the resulting file will be larger.

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

Also, regardless of the mode chosen, add:

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

To start recording, use thestartActivityForResult method:

val intent = OzLivenessSDK.createStartIntent(listOf(OzAction.Smile, OzAction.Blank))
startActivityForResult(intent, REQUEST_CODE)

List<OzAction> actions  = Arrays.asList(OzAction.Smile, OzAction.Scan);
Intent intent = OzLivenessSDK.createStartIntent(actions);
startActivityForResult(intent, REQUEST_CODE);

actions – a list of user actions while recording video.

For Fragment, use the code below. LivenessFragment is the Fragment representation of the Liveness screen UI.

childFragmentManager.beginTransaction()
    .replace(R.id.content, LivenessFragment.create(actions))
    .commit()
// subscribing to the Fragment result
childFragmentManager.setFragmentResultListener(OzLivenessSDK.Extra.REQUEST_CODE, this) { _, result ->
    when (result.getInt(OzLivenessSDK.Extra.EXTRA_RESULT_CODE)) {
        OzLivenessResultCode.SUCCESS -> { /* start analysis */ }
        else -> { /* show error */ }  
    }
}

getSupportFragmentManager().beginTransaction()
        .replace(R.id.content, LivenessFragment.Companion.create(actions, null, null, false))
        .addToBackStack(null)
        .commit();
// subscribing to the Fragment result
getSupportFragmentManager().setFragmentResultListener(OzLivenessSDK.Extra.REQUEST_CODE, this, (requestKey, result) -> {
            switch (result.getInt(OzLivenessSDK.Extra.EXTRA_RESULT_CODE)) {
                case OzLivenessResultCode.SUCCESS: {/* start analysis */}
                default: {/* show error */}
            }
        });

To obtain the captured video, use theonActivityResult method:

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

@Override
protected void onActivityResult(int requestCode, int resultCode, @androidx.annotation.Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE) {
        List<OzAbstractMedia> sdkMediaResult = OzLivenessSDK.INSTANCE.getResultFromIntent(data);
        String sdkErrorString = OzLivenessSDK.INSTANCE.getErrorFromIntent(data);
    }

• sdkMediaResult – an object with video capturing results for interactions with Oz API (a list of the OzAbstractMedia objects),

• sdkErrorString – description of errors, if any.

If a user closes the capturing screen manually, resultCode receives the Activity.RESULT_CANCELED value.

Code example:

when (resultCode) {
    Activity.RESULT_CANCELED -> *USER CLOSED THE SCREEN*
    OzLivenessResultCode.SUCCESS -> {
        val sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
        *SUCCESS*
    }
    else -> {
        val errorMessage = OzLivenessSDK.getErrorFromIntent(data)
        *FAILURE*
    }
}

To connect SDK to Oz API, specify the API URL and access token as shown below.

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

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

Alternatively, you can use the login and password provided by your Oz Forensics account manager:

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 */ }
        }
);

Although, the preferred option is authentication via access token – for security reasons.

By default, logs are saved along with the analyses' data. If you need to keep the logs distinct from the analysis data, set up the separate connection for telemetry as shown below:

OzLivenessSDK.setEventsConnection(
    OzConnection.fromCredentials(
        "https://tm.ozforensics.com/",
        "<your_telemetry_user_eg_tm@company.com>",
        "your_telemetry_password"
    )
)

OzLivenessSDK.setEventsConnection(
        OzConnection.fromCredentials(
                "https://tm.ozforensics.com/",
                "<your_telemetry_user_eg_tm@company.com>",
                "your_telemetry_password"
        )
);

Clearing authorization:

OzLivenessSDK.setApiConnection(null)

OzLivenessSDK.INSTANCE.setApiConnection(null, null);

Other Methods

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

val isLoggedIn = OzLivenessSDK.isLoggedIn

boolean isLoggedIn = OzLivenessSDK.INSTANCE.isLoggedIn();

LogOut:

OzLivenessSDK.logout()

OzLivenessSDK.INSTANCE.logout();

You can generate the trial license here or contact us by email to get a productive license. To create the license, your applicationId (bundle id) is required.

To pass your license file to the SDK, call the OzLivenessSDK.init method with a list of LicenseSources. Use one of the following:

• LicenseSource.LicenseAssetId should contain a path to a license file called forensics.license, which has to be located in the project's res/raw folder.

• LicenseSource.LicenseFilePath should contain a file path to the place in the device's storage where the license file is located.

OzLivenessSDK.init(context,
    listOf(
        LicenseSource.LicenseAssetId(R.raw.your_license_name),
        LicenseSource.LicenseFilePath("absolute_path_to_your_license_file")
    ),
    object : StatusListener<LicensePayload> {
        override fun onSuccess(result: LicensePayload) { /*check the license payload*/ }
        override fun onError(error: OzException) { /*handle the exception */ }
    }
  )

OzLivenessSDK.INSTANCE.getConfig().setBaseURL(BASE_URL);
OzLivenessSDK.INSTANCE.init(context,
    Arrays.asList(
        new LicenseSource.LicenseAssetId(R.raw.forensics),
        new LicenseSource.LicenseFilePath("absolute_path_to_your_license_file")
    ),
    new StatusListener<LicensePayload>() {
        @Override public void onStatusChanged(@Nullable String s) {}
        @Override public void onSuccess(LicensePayload licensePayload) { /*check the license payload*/ }
        @Override public void onError(@NonNull OzException e) { /*handle the exception */ }
    }
);

In case of any license errors, the onError function is called. Use it to handle the exception as shown above. Otherwise, the system will return information about license. To check the license data manually, use the getLicensePayload method.

Possible License Errors

If you use our SDK just for capturing videos, omit this step.

To check liveness and face biometry, you need to upload media to our system and then analyze them.

Here’s an example of performing a check:

analysisCancelable = AnalysisRequest.Builder()
 // mediaToAnalyze is an array of OzAbstractMedia that were captured or otherwise created 
    .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaToAnalyze))// or ON_DEVICE if you want the on-device analysis
    .build()
//initiating the analyses and setting up a listener
    .run(object : AnalysisRequest.AnalysisListener {
        override fun onStatusChange(status: AnalysisRequest.AnalysisStatus) { handleStatus(status) // or your status handler
        }
        override fun onSuccess(result: RequestResult) {
            handleResults(result) // or your result handler
        }
        override fun onError(error: OzException) { handleError(error) // or your error handler 
        }
    })

analysisCancelable = new AnalysisRequest.Builder()
// mediaToAnalyze is an array of OzAbstractMedia that were captured or otherwise created 
        .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaToAnalyze)) // or ON_DEVICE if you want the on-device analysis
        .build()
//initiating the analyses and setting up a listener
        .run(new AnalysisRequest.AnalysisListener() { 
            @Override
            public void onSuccess(@NonNull RequestResult list) { handleResults(list); } // or your result handler
            @Override
            public void onError(@NonNull OzException e) { handleError(e); } // or your error handler
            @Override
            public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) { handleStatus(analysisStatus); } // or your status handler
        })

To delete media files after the checks are finished, use the clearActionVideos method.

Adding Metadata

To add metadata to a folder, use the addFolderMeta method.

    .addFolderMeta(
        mapOf(
            "key1" to "value1",
            "key2" to "value2"
        )
    )

.addFolderMeta(Collections.singletonMap("key", "value")) 

Extracting the Best Shot

In the params field of the Analysis structure, you can pass any additional parameters (key + value), for instance, to extract the best shot on the server side.

mapOf("extract_best_shot" to true)

Using Media from Another SDK

To use a media file that is captured with another SDK (not Oz Android SDK), specify the path to it in OzAbstractMedia:

       val file = File(context.filesDir, "media.mp4") // use context.getExternalFilesDir(null) instead of context.filesDir for external app storage
       val media = OzAbsractMedia.OzVideo(OzMediaTag.VideoSelfieSmile, file.absolutePath)

Adding Media to a Certain Folder

If you want to add your media to the existing folder, use the setFolderId method:

    .setFolderId(folderId)

If you want to get back to the previous (up to 6.4.2) versions' design, reset the customization settings of the capture screen and apply the parameters that are listed below.

OzLivenessSDK.config.customization = UICustomization(
    // customization parameters for the toolbar
    toolbarCustomization = ToolbarCustomization(
        closeIconTint = Color.ColorHex("#FFFFFF"),
        backgroundColor = Color.ColorHex("#000000"),
        backgroundAlpha = 100,
    ),
    // customization parameters for the center hint
    centerHintCustomization = CenterHintCustomization(
        verticalPosition = 70
    ),
    // customization parameters for the hint animation
    new HintAnimation(
        hideAnimation = true
    ),
    // customization parameters for the frame around the user face
    faceFrameCustomization = FaceFrameCustomization(
        strokeDefaultColor = Color.ColorHex("#EC574B"),
        strokeFaceInFrameColor = Color.ColorHex("#00FF00"),
        strokeWidth = 6,
    ),
    // customization parameters for the background outside the frame
    backgroundCustomization = BackgroundCustomization(
        backgroundAlpha = 100
    ),
)

OzLivenessSDK.INSTANCE.getConfig().setCustomization(new UICustomization(
// customization parameters for the toolbar
new ToolbarCustomization(
    R.drawable.ib_close,
    new Color.ColorHex("#FFFFFF"),
    new Color.ColorHex("#000000"),
    100, // toolbar text opacity (in %)
    ),
// customization parameters for the center hint
new CenterHintCustomization(
    70, // vertical position (in %)
),
// customization parameters for the hint animation
new HintAnimation(
    true, // hide animation
),
// customization parameters for the frame around the user face
new FaceFrameCustomization(     
    new Color.ColorHex("#EC574B"), 
    new Color.ColorHex("#00FF00"),
    6, // frame stroke width (in dp)
 ),
// customization parameters for the background outside the frame
new BackgroundCustomization(
    100 // background opacity (in %)
),
  )
);

Configuration

We recommend applying these settings when starting the app.

// connecting to the API server
OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(HOST, TOKEN))
// settings for the number of attempts to detect an action
OzLivenessSDK.config.attemptSettings = attemptSettings 
// the possibility to display additional debug information (you can do it by clicking the SDK version number)
OzLivenessSDK.config.allowDebugVisualization = allowDebugVisualization 
// logging settings
OzLivenessSDK.config.logging = ozLogging 

OzConfig config = OzLivenessSDK.INSTANCE.getConfig();
// connecting to the API server
OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(HOST, TOKEN));
// settings for the number of attempts to detect an action
config.setAttemptSettings(attemptSettings); 
// the possibility to display additional debug information (you can do it by clicking the SDK version number)
config.setAllowDebugVisualization(allowDebugVisualization); 
// logging settings
config.setLogging(ozLogging); 

Interface Customization

To customize the Oz Liveness interface, use UIcustomization as shown below. For the description of customization parameters, please refer to Android SDK Methods and Properties.

OzLivenessSDK.config.customization = UICustomization(
    // customization parameters for the toolbar
    toolbarCustomization = ToolbarCustomization(
        closeIconRes = R.drawable.ib_close,
        closeIconTint = Color.ColorRes(R.color.white),
        titleTextFont = R.font.roboto,
        titleTextSize = 18,
        titleTextAlpha = 100,
        titleTextColor = Color.ColorRes(R.color.white),
        backgroundColor = Color.ColorRes(R.color.black),
        backgroundAlpha = 60,
        isTitleCentered = true,
        title = "Analysis"
    ),
    // customization parameters for the center hint
   centerHintCustomization = CenterHintCustomization(
        textFont = R.font.roboto,
        textColor = Color.ColorRes(R.color.text_color),
        textSize = 20,
        verticalPosition = 50,
        textStyle = R.style.Sdk_Text_Primary,
        backgroundColor = Color.ColorRes(R.color.color_surface),
        backgroundOpacity = 56,
        backgroundCornerRadius = 14,
        textAlpha = 100
    ),
    // customization parameters for the hint animation
    hintAnimation = HintAnimation(
    hintGradientColor = Color.ColorRes(R.color.red),
    hintGradientOpacity = 80,
    animationIconSize = 120,
    hideAnimation = false
),
    // customization parameters for the frame around the user face
    faceFrameCustomization = FaceFrameCustomization(
        geometryType = GeometryType.Rectangle(10), // 10 is the corner radius
        strokeDefaultColor = Color.ColorRes(R.color.error_red),
        strokeFaceInFrameColor = Color.ColorRes(R.color.success_green),
        strokeAlpha = 100,
        strokeWidth = 5,
        strokePadding = 3,
    ),
    // customization parameters for the background outside the frame
    backgroundCustomization = BackgroundCustomization(
        backgroundColor = Color.ColorRes(R.color.black),
        backgroundAlpha = 60
    ),
    // customization parameters for the SDK version text
    versionTextCustomization = VersionTextCustomization(
        textFont = R.font.roboto,
        textSize = 12,
        textColor = Color.ColorRes(R.color.white),
        textAlpha = 100,
    ),
    // customization parameters for the antiscam protection text
    antiScamCustomization = AntiScamCustomization(
        textMessage = "",
        textFont = R.font.roboto,
        textSize = 14,
        textColor = Color.ColorRes(R.color.text_color),
        textAlpha = 100,
        backgroundColor = Color.ColorRes(R.color.color_surface),
        backgroundOpacity = 100,
        cornerRadius = 20,
        flashColor = Color.ColorRes(R.color.green)
    ),
    // custom logo parameters
    // should be allowed by license
    logoCustomization = LogoCustomization(
    image = Image.Drawable(R.drawable.ic_logo),
    size = Size(176, 64),
    )
)

OzLivenessSDK.INSTANCE.getConfig().setCustomization(new UICustomization(
// customization parameters for the toolbar
new ToolbarCustomization(
    R.drawable.ib_close,
    new Color.ColorRes(R.color.white),
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.white),
    R.font.roboto,
    Typeface.NORMAL,
    100, // toolbar text opacity (in %)
    18, // toolbar text size (in sp)
    new Color.ColorRes(R.color.black),
    60, // toolbar alpha (in %)
    "Liveness", // toolbar title
    true // center toolbar title
    ),
// customization parameters for the center hint
new CenterHintCustomization(
    R.font.roboto,
    new Color.ColorRes(R.color.text_color),
    20,
    50,
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.color_surface),
    100, // background opacity
    14, // corner radius for background frame   
    100 // text opacity
    ),
// customization parameters for the hint animation
new HintAnimation(
    new Color.ColorRes(R.color.red), // gradient color
    80, // gradient opacity (in %)
    120, // the side size of the animation icon square
    false // hide animation
    ),
// customization parameters for the frame around the user face
new FaceFrameCustomization(
    GeometryType.RECTANGLE,
    10, // frame corner radius (for GeometryType.RECTANGLE)
    new Color.ColorRes(R.color.error_red), 
    new Color.ColorRes(R.color.success_green),
    100, // frame stroke alpha (in %)
    5, // frame stroke width (in dp)
    3 // frame stroke padding (in dp)
    ),
// customization parameters for the background outside the frame
new BackgroundCustomization(
    new Color.ColorRes(R.color.black),
    60 // background alpha (in %)
    ),
 // customization parameters for the SDK version text
 new VersionTextCustomization(
     R.style.Sdk_Text_Primary,
     R.font.roboto,
     12, // version text size
     new Color.ColorRes(R.color.white),
     100 // version text alpha
     ),
 // customization parameters for the antiscam protection text
 new AntiScamCustomization(
    "Recording .. ",
    R.font.roboto,
    12,
    new Color.ColorRes(R.color.text_color),
    100,
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.color_surface),
    100,
    14,
    new Color.ColorRes(R.color.green)
    )
// custom logo parameters
 new LogoCustomization(
    new Image.Drawable(R.drawable.ic_logo),
    new Size(176, 64)
    )
  )
);

By default, SDK uses the locale of the device. To switch the locale, use the code below:

OzLivenessSDK.config.localizationCode = OzLivenessSDK.OzLocalizationCode.EN

OzLivenessSDK.INSTANCE.getConfig().setLocalizationCode(OzLivenessSDK.OzLocalizationCode.EN)

To start using Oz Android SDK, follow the steps below.

1. Embed Oz Android SDK into your project as described here.

2. Get a trial license for SDK on our website or a production license by email. We'll need your application id. Add the license to your project as described here.

3. Connect SDK to API as described here. This step is optional, as this connection is required only when you need to process data on a server. If you use the on-device mode, the data is not transferred anywhere, and no connection is needed.

4. Capture videos using methods described here. You'll send them for analysis afterward.

5. Analyze media you've taken at the previous step. The process of checking liveness and face biometry is described here.

6. If you want to customize the look-and-feel of Oz Android SDK, please refer to this section.

Resources

Recommended Android version: 5+ (the newer the smartphone is, the faster the analyses are).

Recommended versions of components:

We do not support emulators.

Available languages: EN, ES, HY, KK, KY, TR, PT-BR.

To obtain the sample apps source code for the Oz Liveness SDK, proceed to the GitLab repository:

Follow the link below to see a list of SDK methods and properties:

Download the demo app latest build here.

8.15.0 – Dec. 30, 2024

• Changed the wording for the head_down gesture: the new wording is “tilt down”.

• Added proper focus order for TalkBack when the antiscam hint is enabled.

• Added the public setting extract_action_shot in the Demo Application.

• Fixed bugs.

• Security updates.

8.14.1 – Dec. 5, 2024

• Fixed the bug when the recorded videos might appear green.

• Resolved codec issues on some smartphone models.

8.14.0 – Dec. 2, 2024

• Accessibility updates according to WCAG requirements: the SDK hints and UI controls can be voiced.

• Improved user experience with head movement gestures.

• Moved the large video compression step to the Liveness screen closure.

• Fixed the bug when the best shot frame could contain an image with closed eyes.

• Minor bug fixes and telemetry updates.

8.13.0 – Nov. 12, 2024

• Security and telemetry updates.

8.12.4 – Oct. 01, 2024

• Security updates.

8.12.2 – Sept. 10, 2024

• Security updates.

8.12.0 – Aug. 29, 2024

• Security and telemetry updates.

8.11.0 – Aug. 19, 2024

• Fixed the RuntimeException error with the server-based Liveness that appeared on some devices.

• Security updates.

8.10.0 – July 26, 2024

• Security updates.

• Bug fixes.

8.9.0 – July 18, 2024

• Updated the Android Gradle plugin version to 8.0.0.

• Internal SDK improvements.

8.8.3 – July 11, 2024

• Internal SDK improvements.

8.8.2 – June 21, 2024

• Security updates.

8.8.1 – June 12, 2024

• Security updates.

8.8.0 – June 04, 2024

• Security updates.

8.7.3 – June 03, 2024

• Security updates.

8.7.0 – May 06, 2024

• Added a description for the error that occurs when providing an empty string as an ID in the setFolderID method.

• Fixed a bug causing an endless spinner to appear if the user switches to another application during the Liveness check.

• Fixed some smartphone model specific-bugs.

8.6.0 – Apr. 05, 2024

• Upgraded the on-device Liveness model.

• Security updates.

8.5.0 – Feb. 27, 2024

• Removed the pause after the Scan gesture.

• If the recorded video is larger than 10 MB, it gets compressed.

• Security and logging updates.

8.4.4 – Feb. 06, 2024

• Changed the master license validation algorithm.

8.4.3 – Jan. 29, 2024

• Downgraded the required compileSdkVersion from 34 to 33.

8.4.2 – Jan. 15, 2024

• Security updates.

8.4.0 – Jan. 04, 2024

• Updated the on-device Liveness model.

• Fixed some bugs.

8.3.3 – Dec. 11, 2023

• Internal licensing improvements.

8.3.2 – Nov. 30, 2023

• Internal SDK improvements.

8.3.1 – Nov. 24, 2023

• Bug fixes.

8.3.0 – Nov. 17, 2023

• Implemented the possibility of using a master license that works with any bundle_id.

• Video compression failure on some phone models is now fixed.

8.2.1 – Nov. 01, 2023

• Bug fixes.

8.2.0 – Oct. 23, 2023

• The Analysis structure now contains the sizeReductionStrategy field. This field defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully.

• The messages for the errors that are retrieved from API are now detailed.

8.1.1 – Oct. 02, 2023

8.1.0 – Sept. 07, 2023

• Updated the Liveness on-device model.

• Added the Portuguese (Brazilian) locale.

• If a media hasn't been uploaded correctly, the system repeats the upload.

• Created a new method to retrieve the telemetry (logging) identifier: getEventSessionId.

• The login and auth methods are now deprecated. Use the setAPIConnection method instead.

• OzConfig.baseURL and OzConfig.permanentAccessToken are now deprecated.

• If a user closes the screen during video capture, the appropriate error is now being handled by SDK.

• Fixed some bugs and improved the SDK work.

8.0.3 – Aug. 24, 2023

• Fixed errors.

8.0.2 – July 13, 2023

• The SDK now works properly with baseURL set to null.

8.0.1 – June 28, 2023

• The dependencies' versions have been brought into line with Kotlin version.

8.0.0 – June 19, 2023

• Added the new analysis mode – hybrid (Liveness only). If the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.

• Kotlin version requirements lowered to 1.7.21.

• Improved the on-device models.

• For some phone models, fixed the fatal device error.

• The hint text width can now exceed the frame width (when using the main camera).

• Photos taken during the One Shot analysis are now being sent to the server in the original size.

• Removed the OzAnalysisResult class. The onSuccess method ofAnalysisRequest.run now uses the RequestResult structure instead of List<OzAnalysisResult>.

• All exceptions are moved to the com.ozforensics.liveness.sdk.core.exceptions package (See changes below).

• Classes related to AnalysisRequest are moved to the com.ozforensics.liveness.sdk.analysispackage (See changes below).

• The methods below are no longer supported:

7.3.1 – June 07, 2023

• Restructured the settings screen.

• Added the center hint background customization.

• Added new face frame forms (Circle, Square).

• The OzLivenessSDK::init method no longer crashes if there is a StatusListener parameter passed.

• Changed the scan gesture animation.

7.2.0 – May 04, 2023

• Improved the SDK algorithms.

7.1.4 – Mar. 30, 2023

• Updated the model for the on-device analyses.

• Fixed the animation for sunglasses/mask.

• The oval size for Liveness is now smaller.

7.1.3 – Mar. 03, 2023

• Fixed the error with the server-based analyses while using permanentAccessToken for authorization.

7.1.2 – Feb. 22, 2023

• You can now hide the status bar and system buttons (works with 7.0.0 and higher).

• OzLivenessSDK.init now requires context as the first parameter.

• OzAnalysisResult now shows the server-based analyses' scores properly.

• Fixed initialization issues, displaying of wrong customization settings, authorization failures on Android <7.1.1.

7.1.1 – Jan. 16, 2023

• Fixed crashes for Android v.6 and below.

• Fixed oval positioning for some phone models.

• Internal fixes and improvements.

7.1.0 – Dec. 16, 2022

• Updated security.

• Implemented some internal improvements.

• The addMedia method is now deprecated, please use uploadMedia for uploading.

7.0.0 – Nov. 23, 2022

• Changed the way of sharing dependencies. Due to security issues, now we share two types of libraries as shown below: sdk is a server analysis only, full provides both server and on-device analyses:

• UICustomization has been implemented instead of OzCustomization.

• Added the Spanish locale.

6.4.2.3

• Fixed the bug with freezes that had appeared on some phone models.

• SDK now captures videos in 720p.

6.4.1

• Synchronized the names of the analysis modes with iOS: SERVER_BASED and ON_DEVICE.

• Fixed the bug with displaying of localization settings.

6.4.0

• Now you can use Fragment as Liveness screen.

• Added a new field to the Analysis structure. The params field is for any additional parameters, for instance, if you need to set extracting the best shot on server to true. The best shot algorithm chooses the most high-quality frame from a video.

6.3.7

• The Zoom in and Zoom out gestures are no longer supported.

6.3.6

• Updated the biometry model.

6.3.5

• Added a new simplified API – AnalysisRequest. With it, it’s easier to create a request for the media and analysis you need.

6.3.4

• Published the on-device module for on-device liveness and biometry analyses. To add this module to your project, use:

To launch these analyses, use runOnDeviceBiometryAnalysis and runOnDeviceLivenessAnalysis methods from the OzLivenessSDK class:

6.3.3

• Liveness now goes smoother.

• Fixed freezes on Xiaomi devices.

• Optimized image converting.

6.3.1

• New metadata parameter for OzLivenessSDK.uploadMedia and new OzLivenessSDK.uploadMediaAndAnalyze method to pass this parameter to folders.

6.2.8

• Added functions for SDK initialization with LicenseSources: LicenseSource.LicenseAssetId and LicenseSource.LicenseFilePath. Use the OzLivenessSDK.init method to start initialization.

• Now you can get the license info upon initialization val licensePayload = OzLivenessSDK.getLicensePayload().

6.2.4

• Added the Kyrgyz locale.

6.2.0

• Added local analysis functions.

• You can now configure the face frame.

• Fixed version number at the Liveness screen.

6.1.0

• Added the main camera support.

6.0.1

• Added configuration from license support.

6.0.0

• Added the OneShot gesture.

• Added new states for OzAnalysisResult.Resolution.

• Added the uploadMediaAndAnalyze method to load a bunch of media to the server at once and send them to analysis immediately.

• OzMedia is renamed to OzAbstractMedia and got subclasses for images and videos.

• Fixed camera bugs for some devices.

5.1.0

• Access token updates automatically.

• Renamed accessToken to permanentAccessToken.

• Added R8 rules.

• Configuration became easier: config settings are mutable.

5.0.2

• Fixed the oval frame.

• Removed the unusable parameters from AnalyseRequest.

• Removed default attempt limits.

5.0.0

• To customize the configuration options, the config property is added instead of baseURL, accessToken, etc. Use OzConfig.Builder for initialization.

• Added license support. Licences should be installed as raw resources. To pass them to OzConfig, use setLicenseResourceId.

• Replaced the context-dependent methods with analogs.

• Improved the image analysis.

• Removed unusable dependencies.

• Fixed logging.

Please note: this feature has been implemented in 8.1.0.

To add or update the language pack for Oz Android SDK, please follow these instructions:

1. Go to the folder for the locale needed, or create a new folder. Proceed to this guide for the details.

2. Create the file called strings.xml.

3. Copy the strings from the attached file to your freshly created file.

4. Redefine the strings you need in the appropriate localization records.

A list of keys for Android:

The keys action_*_go refer to the appropriate gestures. Others refer to the hints for any gesture, info messages, or errors.

When new keys appear with new versions, if no translation is provided in your file, the new strings are shown in English.

OzLivenessSDK

A singleton for Oz SDK.

clearActionVideos

Deletes all action videos from file system.

Parameters

-

Returns

-

createStartIntent

Creates an intent to start the Liveness activity.

Returns

-

getErrorFromIntent

Utility function to get the SDK error from OnActivityResult's intent.

Returns

getLicensePayload

Retrieves the SDK license payload.

Parameters

-

Returns

getResultFromIntent

Utility function to get SDK results from OnActivityResult's intent.

Returns

A list of OzAbstractMedia objects.

init

Initializes SDK with license sources.

Returns

-

log

Enables logging using the Oz Liveness SDK logging mechanism.

Returns

-

setApiConnection

Connection to API.

setEventsConnection

Connection to the telemetry server.

logout

Deletes the saved token.

Parameters

-

Returns

-

getEventSessionId

Retrieves the telemetry session ID.

Parameters

-

Returns

The telemetry session ID (String parameter).

version

Retrieves the SDK version.

Parameters

-

Returns

The SDK version (String parameter).

generateSignedPayload

Generates the payload with media signatures.

Returns

Payload to be sent along with media files that were used for generation.

AnalysisRequest

A class for performing checks.

run

The analysis launching method.

class Builder

A builder class for AnalysisRequest.

build

Creates the AnalysisRequest instance.

Parameters

-

Returns

addAnalysis

Adds an analysis to your request.

Returns

Error if any.

addAnalyses

Adds a list of analyses to your request. Allows executing several analyses for the same folder on the server side.

Returns

Error if any.

addFolderMeta

Adds metadata to a folder you create (for the server-based analyses only). You can add a pair key-value as additional information to the folder with the analysis result on the server side.

Returns

Error if any.

uploadMedia

Uploads one or more media to a folder.

Returns

Error if any.

setFolderId

For the previously created folder, sets a folderId. The folder should exist on the server side. Otherwise, a new folder will be created.

Returns

Error if any.

OzConfig

Configuration for OzLivenessSDK (use OzLivenessSDK.config).

setSelfieLength

Sets the length of the Selfie gesture (in milliseconds).

Returns

Error if any.

allowDebugVisualization

The possibility to enable additional debug info by clicking on version text.

attemptSettings

The number of attempts before SDK returns error.

uploadMediaSettings

Settings for repeated media upload.

faceAlignmentTimeout

Timeout for face alignment (measured in milliseconds).

livenessErrorCallback

Interface implementation to retrieve error by Liveness detection.

localizationCode

Locale to display string resources.

logging

Logging settings.

useMainCamera

Uses the main (rear) camera instead of the front camera for liveness detection.

UICustomization

Customization for OzLivenessSDK (use OzLivenessSDK.config.customization).

hideStatusBar

Hides the status bar and the three buttons at the bottom. The default value is True.

toolbarCustomization

A set of customization parameters for the toolbar.

centerHintCustomization

A set of customization parameters for the center hint that guides a user through the process of taking an image of themselves.

hintAnimation

A set of customization parameters for the hint animation.

faceFrameCustomization

A set of customization parameters for the frame around the user face.

backgroundCustomization

A set of customization parameters for the background outside the frame.

versionTextCustomization

A set of customization parameters for the SDK version text.

antiscamCustomization

A set of customization parameters for the antiscam message that warns user about their actions being recorded.

logoCustomization

Logo customization parameters. Custom logo should be allowed by license.

Variables and Objects

enum OzAction

Contains the action from the captured video.

class LicensePayload

Contains the extended info about licensing conditions.

sealed class OzAbstractMedia

A class for the captured media that can be:

OzDocumentPhoto

A document photo.

OzShotSet

A set of shots in an archive.

OzVideo

A Liveness video.

enum OzMediaTag

Contains an action from the captured video.

sealed class LicenseSource

A class for license that can be:

LicenseAssetId

Contains the license ID.

LicenseFilePath

Contains the path to a license.

class AnalysisStatus

A class for analysis status that can be:

RunningAnalysis

This status means the analysis is launched.

UploadingMedia

This status means the media is being uploaded.

enum Type

The type of the analysis.

enum Mode

The mode of the analysis.

class Analysis

Contains information on what media to analyze and what analyses to apply.

enum Resolution

The general status for all analyses applied to the folder created.

class OzAttemptsSettings

Holder for attempts counts before SDK returns error.

enum OzLocalizationCode

class OzLogging

Contains logging settings.

sealed class Color

A class for color that can be (depending on the value received):

ColorRes

ColorHex

ColorInt

enum GeometryType

Frame shape settings.

class AnalysisError

Exception class for AnalysisRequest.

class SourceMedia

Structure that describes media used in AnalysisRequest.

class ResultMedia

Structure that describes the analysis result for the single media.

class RequestResult

Consolidated result for all analyses performed.

class AnalysisResult

Result of the analysis for all media it was applied to.

class OzConnection

Defines the authentication method.

OzConnection.fromServiceToken

Authentication via token.

OzConnection.fromCredentials

Authentication via credentials.

class OzUploadMediaSettings

Defines the settings for the repeated media upload.

enum SizeReductionStrategy

Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully. By default, the system uploads the compressed video.

Error Description