Oz Mobile SDK stands for the Software Developer’s Kit of the Oz Forensics Liveness and Face Biometric System, providing seamless integration with customers’ mobile apps for login and biometric identification.

You can generate the trial license or contact us by 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.

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

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

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

for the server-based version only

Please note: this is the default version.

for both server-based and on-device versions

Please note: the resulting file will be larger.

Also, regardless of the mode chosen, add:

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*
    }
}

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 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();

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)

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.

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.

The common way of Oz Mobile SDK to work is the server-based mode, when the Liveness and Biometry analyses are performed on a server as shown in the scheme below:

But there's also an option to perform checks without server calls or even Internet connection. This option stands for on-device analyses.

The on-device analyses are being performed faster and more secure as all data is processed directly on device, nothing is being sent anywhere. In this case, you don’t need a server at all, neither need you the API connection.

The on-device analysis mode is useful when:

• you do not collect, store or process personal data;

• you need to identify a person quickly regardless of network conditions such as a distant region, inside a building, underground, etc.;

• you’re on a tight budget as you can save money on the hardware part.

Launching the On-Device Analysis

To launch the on-device check, set the appropriate mode for Android or iOS SDK.

Android:

analysisCancelable = AnalysisRequest.Builder()
    .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaToAnalyze))

analysisCancelable = new AnalysisRequest.Builder()
    .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaList)) 

iOS:

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .onDevice)

For details, please refer to the Checking Liveness and Face Biometry sections for iOS and Android.

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 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.

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.

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:

Creating a Public Key

To create a public key, run this command.

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:

License setting:

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

Signature creation example:

Pass the signature as the masterLicenseSignature parameter either during the SDK initialization or license setting.

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.

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

1. Embed Oz iOS SDK into your project as described .

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

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

4. Capture videos by creating the controller as described . You'll send them for analysis afterwards.

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

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

Resources

Minimal iOS version: 11.

Minimal Xcode version: 15 for versions 8.10.0 and newer.

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

A sample app source code using the Oz Liveness SDK is located in the GitLab repository:

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

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

OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://sandbox.ohio.ozforensics.com", token: token)) { (token, error) in
}

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

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Your code to handle error or token
}

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:

let eventsConnection = Connection.fromCredentials(host: https://tm.ozforensics.com/,
                                login: <your_telemetry_user_eg_tm@company.com>,
                                password: your_telemetry_password)
OZSDK.setEventsConnection(eventsConnection) { (token, error) in
}

CocoaPods

To integrate OZLivenessSDK into an Xcode project via the CocoaPods dependency manager, add the following code to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => 'VERSION'

Version is optional as, by default, the newest version is integrated. However, if necessary, you can find the older version number in Changelog.

Since 8.1.0, you can also use a simpler code:

// for the latest version
pod ‘OZLivenessSDK’
// OR, for the specific version
// pod ‘OZLivenessSDK’, ‘8.10.0’

By default, the full version is being installed. It contains both server-based and on-device analysis modes. To install the server-based version only, use the following code:

pod 'OZLivenessSDK/Core', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios.git',  :tag => 'VERSION'

For 8.1.0 and higher:

pod ‘OZLivenessSDK/Core’
// OR
// pod ‘OZLivenessSDK/Core’, ‘8.1.0’

SPM

Please note: installation via SPM is available for versions 8.7.0 and above.

Add the following package dependencies via SPM: https://gitlab.com/oz-forensics/oz-mobile-ios-sdk (if you need a guide on adding the package dependencies, please refer to the Apple documentation). OzLivenessSDK is mandatory. If you don't need the on-device analyses, skip the OzLivenessSDKOnDevice file.

Manual Installation

You can also add the necessary frameworks to your project manually.

1. Download the SDK files from here and add them to your project.

• OZLivenessSDK.xcframework,

• OZLivenessSDKResources.bundle,

• OZLivenessSDKOnDeviceResources.bundle (if you don't need the on-device analyses, skip this file).

1. Download the TensorFlow framework 2.11 from here.

2. Make sure that:

• both xcframework are in Target-Build Phases -> Link Binary With Libraries and Target-General -> Frameworks, Libraries, and Embedded Context;

• the bundle file(s) are in Target-Build Phases -> Copy Bundle Resources.

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.

// customization parameters for the toolbar
let toolbarCustomization = ToolbarCustomization(
   closeButtonColor: .white,
   backgroundColor: .black)

// customization parameters for the center hint
let centerHintCustomization = CenterHintCustomization(
   verticalPosition: 70)
   
// customization parameters for the center hint animation
let hintAnimationCustomization = HintAnimationCustomization(
    hideAnimation: true)

// customization parameters for the frame around the user face
let faceFrameCustomization = FaceFrameCustomization(
   strokeWidth: 6,
   strokeFaceAlignedColor: .green,
   strokeFaceNotAlignedColor: .red)

// customization parameters for the background outside the frame
let backgroundCustomization = BackgroundCustomization(
   backgroundColor: .clear)

OZSDK.customization = OZCustomization(toolbarCustomization: toolbarCustomization,
   centerHintCustomization: centerHintCustomization,
   hintAnimationCustomization: hintAnimationCustomization,
   faceFrameCustomization: faceFrameCustomization,
   versionCustomization: vesrionCustomization,
   backgroundCustomization: backgroundCustomization)

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.

Below, you'll see the example of performing a check and its description.

let analysisRequest = AnalysisRequestBuilder()
// create one or more analyses
let analysis = Analysis.init(
	media: mediaToAnalyze, // mediaToAnalyze is an array of OzMedia that were captured or otherwise created
	type: .quality, // check the analysis types in iOS methods
	mode: .serverBased) // or .onDevice if you want the on-device analysis
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
// initiate the analyses
analysisRequest.run(
	statusHandler: { state in }, // scenario steps progress handler
	errorHandler: { _ in }  
) { result in
    // receive and handle analyses results here 
}

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

Adding Metadata

To add metadata to a folder, use AnalysisRequest.addFolderMeta.

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
var folderMeta: [String: Any] = ["key1": "value1"]
analysisRequest.addFolderMeta(folderMeta)
...

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.

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased, params: [“extract_best_shot” : true])

Using Media from Another SDK

To use a media file that is captured with another SDK (not Oz iOS SDK), specify the path to it in the OzMedia structure (the bestShotURL property):

let referenceMedia = OZMedia.init(movement: .selfie,
                  mediaType: .movement,
                  metaData: ["meta":"data"],
                  videoURL: nil,
                  bestShotURL: imageUrl,
                  preferredMediaURL: nil,
                  timestamp: Date())

Adding Media to a Certain Folder

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

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
analysisRequest.addFolderId(IdRequired)

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

// customization parameters for the toolbar
let toolbarCustomization = ToolbarCustomization(
   closeButtonIcon: UIImage(named: "example"),
   closeButtonColor: .black.withAlphaComponent(0.8),
   titleText: "",
   titleFont: .systemFont(ofSize: 18, weight: .regular),
   titleColor: .gray,
   backgroundColor: .lightGray)

// customization parameters for the center hint
let centerHintCustomization = CenterHintCustomization(
   textColor: .white,
   textFont: .systemFont(ofSize: 22, weight: .regular),
   verticalPosition: 42,
   backgroundColor: UIColor.init(hexRGBA: "1C1C1E8F")!,
   hideTextBackground: false,
   backgroundCornerRadius: 14)
   
// customization parameters for the center hint animation
let hintAnimationCustomization = HintAnimationCustomization(
    hideAnimation: false,
    animationIconSize: 80,
    toFrameGradientColor: UIColor.red)

// customization parameters for the frame around the user face
let faceFrameCustomization = FaceFrameCustomization(
   strokeWidth: 4,
   strokeFaceAlignedColor: .green,
   strokeFaceNotAlignedColor: .red,
   geometryType: .rect(cornerRadius: 10),
   strokePadding: 3)

// customization parameters for the SDK version text
let versionCustomization = VersionLabelCustomization(
   textFont: .systemFont(ofSize: 12, weight: .regular),
   textColor: .gray
)

// customization parameters for the background outside the frame
let backgroundCustomization = BackgroundCustomization(
   backgroundColor: .lightGray
)

// customization parameters for the antiscam protection text
let antiscamCustomization: AntiscamCustomization = AntiscamCustomization(
  customizationEnableAntiscam: false,
  customizationAntiscamTextMessage: "Face recognition",
  customizationAntiscamTextFont: UIFont.systemFont(ofSize: 15, weight: .semibold),
  customizationAntiscamTextColor: UIColor.black,
  customizationAntiscamBackgroundColor: UIColor.init(hexRGBA: "F2F2F7FF")!,
  customizationAntiscamCornerRadius: 18,
  customizationAntiscamFlashColor: UIColor.init(hexRGBA: "FF453AFF")!)

// customization parameters for your logo
// should be allowed by license
let logoCustomization = LogoCustomization(image: UIImage(), size: CGSize(width: 100, height: 100))

OZSDK.customization = Customization(toolbarCustomization: toolbarCustomization,
                   antiscamCustomization: antiscamCustomization,
                   centerHintCustomization: centerHintCustomization,
                   hintAnimationCustomization: hintAnimationCustomization,
                   faceFrameCustomization: faceFrameCustomization,
                   versionCustomization: vesrionCustomization,
                   backgroundCustomization: backgroundCustomization,
                  logoCustomization: logoCustomization)

License

You can generate the trial license here or contact us by email to get a productive license. To create the license, your bundle id is required. After you get a license file, there are two ways to add the license to your project.

1. Rename this file to forensics.license and put it into the project. In this case, you don't need to set the path to the license.

2. During the runtime: when initializing SDK, use the following method.

OZSDK(licenseSources: [.licenseFileName(“forensics.license”)]) { licenseData, error in
      if let error = error {
        print(error)
      }
    }

or

OZSDK(licenseSources: [.licenseFilePath(“path_to_file”)]) { licenseData, error in
      if let error = error {
        print(error)
      }
    }

LicenseSource a source of license, and LicenseData is the information about your license. Please note: this method checks whether you have an active license or not and if yes, this license won't be replaced with a new one. To force the license replacement, use the setLicense method.

In case of any license errors, the system will use your error handling code as shown above. Otherwise, the system will return information about license. To check the license data manually, use OZSDK.licenseData.

Possible License Errors

Create a controller that will capture videos as follows:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(self, actions: actions)
self.present(ozLivenessVC, animated: true)

action – a list of user’s actions while capturing the video.

Once video is captured, the system calls the onOZLivenessResult method:

extension viewController: OZLivenessDelegate {
 func onError(status: OZVerificationStatus?) {
        // show error
   }
 }
 func onOZLivenessResult(results: [OZMedia]) {
   // proceed to the checks step
 }
}

The method returns the results of video capturing: the [OZMedia] objects. The system uses these objects to perform checks.

If a user closes the capturing screen manually, the failedBecauseUserCancelled error appears.

Please find the Flutter repository here.

Installation and Licensing

Add the lines below in pubspec.yaml of the project you want to add the plugin to.

  ozsdk:
    git:
      url: https://gitlab.com/oz-forensics/oz-mobile-flutter-plugin.git
      ref: '8.8.2'

Add the license file (e.g., license.json or forensics.license) to the Flutter application/assets folder. In pubspec.yaml, specify the Flutter asset:

assets
  - assets/license.json // please note that the license file name must match to the one placed in assets

For Android, add the Oz repository to /android/build.gradle, allprojects → repositories section:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url ‘https://ozforensics.jfrog.io/artifactory/main’ } // repository URL
    }
}

For Flutter 8.24.0 and above or Android Gradle plugin 8.0.0 and above, add to android/gradle.properties:

android.nonTransitiveRClass=false

The minimum SDK version should be 21 or higher:

defaultConfig {
  ...
  minSDKVersion 21
  ...
}

For iOS, set the minimum platform to 13 or higher in the Runner → Info → Deployment target → iOS Deployment Target.

In ios/Podfile, comment the use_frameworks! line (#use_frameworks!).

Getting Started with Flutter

Initializing SDK

Initialize SDK by calling the init plugin method. Note that the license file name and path should match the ones specified in pubspec.yaml (e.g., assets/license.json).

await OZSDK.initSDK([<% license path and license file name %>]);

Connecting SDK to API

Use the API credentials (login, password, and API URL) that you’ve received from us.

await OZSDK.setApiConnectionWithCredentials(<login>, <password>, <host>);

In production, instead of hard-coding the login and password inside the application, it is recommended to get the access token on your backend via the API auth method, then pass it to your application:

 await OZSDK.setApiConnectionWithToken(token, host);

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:

await OZSDK.setEventConnectionWithCredentials(<login>, <password>, <host>);

or

await OZSDK.setEventConnectionWithToken(<token>, <host>);

Capturing Videos

To start recording, use the startLiveness method to obtain the recorded media:

await OZSDK.startLiveness(<actions>, <use_main_camera>);

Please note: for versions 8.11 and below, the method name is executeLiveness, and it returns the recorded media.

To obtain the media result, subscribe to livenessResult as shown below:

class Screen extends StatefulWidget {
  static const route = 'liveness';

  const Screen({super.key});

  @override
  State<Screen> createState() => _ScreenState();
}

class _ScreenState extends State<Screen> {
  late StreamSubscription<List<Media>> _subscription;

  @override
  void initState() {
    super.initState();

    // subscribe to liveness result
    _subscription = OZSDK.livenessResult.listen(
      (List<Media> medias) {
          // media contains liveness media
      },
      onError: (Object error) {
        // handle error, in most cases PlatformException
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    // omitted to shorten the example
  }

  void _startLiveness() async {
    // use startLiveness to start liveness screen
    OZSDK.startLiveness(<list of actions>);
  }

  @override
  void dispose() {
    // cancel subscription
    _subscription.cancel();
    super.dispose();
  }
}

Checking Liveness and Face Biometry

To run the analyses, execute the code below.

Create the Analysis object:

List<Analysis> analysis = [ Analysis(Type.quality, Mode.serverBased, <media>, {}), ];

Execute the formed analysis:

final analysisResult = await OZSDK.analyze(analysis, [], {}) ?? [];

The analysisResult list of objects contains the result of the analysis.

If you want to use media captured by another SDK, the code should look like this:

media = Media(FileTypedocumentPhoto, VerificationAction.oneShot, “photo_selfie”, null, <path to image>, null, null, “”)

The whole code block will look like this:

// replace VerificationAction.blank with your Liveness gesture if needed
final cameraMedia = await OZSDK.executeLiveness([VerificationAction.blank], use_main_camera);

final analysis = [
  Analysis(Type.quality, Mode.serverBased, cameraMedia, {}),
];

final analysisResult = await OZSDK.analyze(analysis, [], {});

// replace VerificationAction.blank with your Liveness gesture if needed
final cameraMedia = await OZSDK.executeLiveness([VerificationAction.blank], use_main_camera);
final biometryMedia = [...cameraMedia];
biometryMedia.add(
  Media(
    FileType.documentPhoto,
    VerificationAction.blank,
    MediaType.movement,
    null,
    <your reference image path>,
    null,
    null,
    MediaTag.photoSelfie,
  ),
);

final analysis = [
  Analysis(Type.quality, Mode.serverBased, cameraMedia, {}),
  Analysis(Type.biometry, Mode.serverBased, biometryMedia, {}),
];

final analysisResult = await OZSDK.analyze(analysis, [], {});

In this section, we explain how to use Oz Flutter SDK for iOS and Android.

Before you start, it is recommended that you install:

• Flutter 3.0.0 or higher;

• Android SDK 21 or higher;

• dart 2.18.6 or higher;

• iOS platform 13 or higher;

• Xcode.

Please find the Flutter repository here.

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

The error text – String.

getLicensePayload

Retrieves the SDK license payload.

Parameters

-

Returns

The license payload (LicensePayload) – the object that contains the extended info about licensing conditions.

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

The AnalysisRequest class instance.

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.