How to Integrate Oz Liveness into Your Mobile Application

Oz Liveness Mobile SDK implements the ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results.

This guide walks you through your first liveness check using Mobile SDK (iOS or Android) and Oz API.

The described flow combines:

• Capture mode – the Mobile SDK captures the Liveness video in the app and the Client backend forwards it to Oz API. Capture results are not sent from the SDK straight to Oz API; the Client backend acts as an intermediary.

• OzCapsula – a proprietary encrypted binary container. The SDK packages the captured media into it; only Oz API can decrypt and process it. On the device it is an opaque blob – you cannot decode or inspect it, only forward it as-is.

Each step is marked:

• [Oz SDK] – call our SDK API.

• [Your code] – call your own backend or your own code.

{{host}} in the examples below is the base URL of your Oz API deployment, provided to you during deployment setup.

Requirements

Component	Minimum version
Oz API	6.6.1
iOS SDK	10.0.0
Android SDK	10.0.0
Flutter	10.0.0

Use Content-Type: application/octet-stream for any container uploaded to Oz API.

Before you begin, make sure you have Oz API credentials. When using SaaS API, you get them from us:

Login: [e-mail]
Password: …
API: https://<link>.ozforensics.com
Web Console: https://<link>.ozforensics.com

For the on-premise Oz API, you need to create a user yourself or ask your team that manages the API. See the guide on user creation via Web Console. Consider the proper user role (CLIENT in most cases or CLIENT ADMIN, if you are going to make SDK work with the pre-created folders from other API users). In the end, you need to obtain a similar set of credentials as you would get for the SaaS scenario.

These parameters are mandatory for OzCapsula to work. Define them in your API configuration file.

OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true

We also recommend that you use our logging service called telemetry, as it helps a lot in investigating attacks' details. For Oz API users, the service is enabled by default. For on-premise installations, we'll provide you with credentials.

Oz Liveness Mobile SDK requires a license. License is bound to the bundle_id of your application, e.g., com.yourcompany.yourapp.

Instructions

1

(your code) Add SDK to your project

Android

In the build.gradle of your project, add:

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

In the build.gradle of the module, add:

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // You can find the version needed in the Android changelog
}

iOS

CocoaPods

To integrate OZLivenessSDK into an Xcode project, add to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-mobile-ios-sdk', :tag => '<version>' // You can find the version needed in  iOS changelog

SPM

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. Skip the OzLivenessSDKOnDevice file.

Flutter

Add to pubspec.yaml:

ozsdk: ^10.0.0

2

(Oz SDK) Initialize the SDK with a license

Call once per app launch.

Android

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics)),
    object : StatusListener<LicensePayload> {
        override fun onSuccess(result: LicensePayload) {
            // SDK ready — proceed to Step 3
        }
        override fun onError(error: OzException) {
            // handle license error
        }
    }
)

Connect the telemetry receiver

After the license is loaded, point the SDK at the Oz telemetry receiver so it can send telemetry. Pass the event host along with a service token.

val eventsConnection = OzConnection.fromServiceToken(
    host = "<telemetry-receiver-host>",
    token = "<telemetry-service-token>"
)

OzLivenessSDK.setEventsConnection(eventsConnection, object : StatusListener<String?> {
    override fun onSuccess(accessToken: String?) {
        // telemetry receiver ready — proceed to Step 2
    }
    override fun onError(error: OzException) {
        // handle events connection error
    }
})

The event host and service token are provided by Oz Forensics. They are distinct from the session_token used for capture in Step 2.

iOS

OZSDK(licenseSources: [.licenseFilePath(path)]) { licenseData, error in
    if let error = error {
        // handle license error
    } else {
        // SDK ready — proceed to Step 3
    }
}

Optional language setup:

OZSDK.set(languageBundle: Bundle(for: OzSdk.self))
OZSDK.localizationCode = (lang == "en") ? .en : .custom(lang)

Connect the telemetry receiver

After the license is loaded, point the SDK at the Oz telemetry receiver so it can send telemetry. Pass the event host along with a service token.

let eventsConnection = Connection.fromServiceToken(
    host: "<telemetry-receiver-host>",
    token: "<telemetry-service-token>",
    sslPins: nil
)

OZSDK.setEventsConnection(eventsConnection) { accessToken, error in
    if let error = error {
        // handle events connection error
    } else {
        // telemetry receiver ready — proceed to Step 2
    }
}

The event host and service token are provided by Oz Forensics. They are distinct from the session_token used for capture in Step 2.

Flutter

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

Connect the telemetry receiver

After the license is loaded, point the SDK at the Oz telemetry receiver so it can send telemetry. Pass the event host along with a service token.

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

The event host and service token are provided by Oz Forensics. They are distinct from the session_token used for capture in Step 2.

During development, the SDK's security checks can cause the analysis to be declined – for example, when the app runs with a debugger attached. If you need to run the SDK under these conditions while developing, lower the strictness of the security checks by setting the SDK environment to the debug mode:

Android

OzLivenessSDK.setEnvironment(OzLivenessSDK.Environment.DEBUG)

iOS

OZSDK.setEnvironment(environment: .debug)

Flutter

OZSDK.setEnvironment(debug)

The debug must be used only during development and testing. All release builds must use the default PRODUCTION (Android), .prod (iOS), or production (Flutter) value, where all security checks are enabled.

3

(your code) Get a session_token from your backend

OzCapsula uses a session token. The token is mandatory for OzCapsula.

Your backend requests a session token from Oz API. Request it before each capture session, as close to the moment the user starts capture as possible.

Endpoint:

GET {{host}}/api/authorize/session_token

Request:

curl --location -g '{{host}}/api/authorize/session_token' \
--header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings

The authorization mechanism for calls to Oz API (access_token) depends on your installation settings: when using Instant API, you can integrate it under your own authorization scheme. If access token is required in your case, please check Authentication. Also, please note that access and session token are different tokens issued for different purposes.

Response:

{
  "session_token": "<session_token>"
}

This token is short-lived (default lifetime: 900 seconds for API Full, 120 seconds for Instant API). Request one per capture session and pass it to the SDK immediately – do not cache or reuse tokens across sessions.

4

(Oz SDK) Launch the capture screen with the session_token

Pass the session_token from Step 3.

Android

val captureRequest = CaptureRequest(
    listOf(
        AnalysisProfile(
            Analysis.Type.QUALITY,
            listOf(MediaRequest.ActionMedia(OzAction.Blank))
        )
    )
)
val intent = OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)
startActivityForResult(intent, REQUEST_LIVENESS_CONTAINER)

iOS

let mediaRequest = MediaRequest.action(.selfie)

let profile = AnalysisProfile(
    mediaList: [mediaRequest],
    type: .quality,
    params: [:]
)

let request = CaptureRequest(
    analysisProfileList: [profile],
    cameraPosition: .front
)

let livenessVC = try OZSDK.createMediaCaptureScreen(
    delegate,
    request,
    sessionToken: sessionToken          // from Step 3
)

livenessVC.modalPresentationStyle = .fullScreen
parent.present(livenessVC, animated: true)

Flutter

final sessionToken = await _getSessionToken();
OZSDK.createMediaCaptureScreen(
  CaptureRequest(
    analysisProfileList: [
      AnalysisProfile(
        Type.quality,
        mediaList: [ActionMedia(VerificationAction.blank)]
      ),
    ],
  ),
  sessionToken,
);

5

(Oz SDK) Get the OzCapsula container

The container is an opaque encrypted blob. You cannot decode it, inspect it, or extract individual images / frames / metadata from it on the device. It must be forwarded as-is to your backend. If you need access to captured images (e.g., the best shot), retrieve them from the Oz API analysis response on the server side.

Android

Extract the DataContainer from the result intent.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_LIVENESS_CONTAINER) {
        when (resultCode) {
            OzLivenessResultCode.SUCCESS -> {
                val container = OzLivenessSDK.getContainerFromIntent(data)
                handleContainer(container)
            }
            OzLivenessResultCode.USER_CLOSED_LIVENESS -> { /* user closed the screen */ }
            else -> {
                val errorMessage = OzLivenessSDK.getErrorFromIntent(data)
                /* show error */
            }
        }
    }
}

iOS

Implement the delegate. On success you receive a DataContainer.

extension YourViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
        // Pass container to Step 6
        handleContainer(container)
    }

    func onError(status: OZVerificationStatus?) {
        // user cancelled, capture failed, etc.
    }
}

Flutter

Subscribe to livenessResult; the container arrives as a DataContainer.

@override
void initState() {
  super.initState();
  _subscription = OZSDK.livenessResult.listen((result) {
    if (result is DataContainer) {
      // OzCapsula media
    }
  }, onError: (Object error) {
    // handle error, in most cases PlatformException
  });
}

6

(your code) Send the container to Oz API

Send the encrypted container to your own backend as raw bytes (application/octet-stream). Your backend forwards it to Oz API and returns the analysis response.

Do not run the analysis directly from the mobile SDK. In the embedded-SDK integration flow, the analysis call must go through your own backend.

Android

The code below is illustrative – YourBackend.uploadOzContainer(...) is not part of Oz SDK. You implement this method yourself in your own backend client; Oz SDK does not provide an upload helper for this integration path.

private fun handleContainer(container: DataContainer?) {
    if (container == null) return

    YourBackend.uploadOzContainer(
        container = container.getBytes(),
        contentType = "application/octet-stream"
    )
}

Do not call AnalysisRequest.Builder().addContainer(...).build().run(...).

iOS

The code below is illustrative – YourBackend.uploadOzContainer is not part of Oz SDK. You implement this method yourself in your own backend client; Oz SDK does not provide an upload helper for this integration path.

func handleContainer(_ container: DataContainer) {
    YourBackend.uploadOzContainer(
        container,
        contentType: "application/octet-stream"
    ) { result in
        DispatchQueue.main.async {
            self.handleAnalysisResult(result)
        }
    }
}

Do not call AnalysisRequestBuilder / AnalysisRequest.run(...).

Flutter

The code below is illustrative – YourBackend.uploadOzContainer is not part of Oz SDK. You implement this method yourself in your own backend client; Oz SDK does not provide an upload helper for this integration path.

final Uint8List? containerBytes = await OZSDK.getContainerBytes(dataContainer);
await YourBackend.uploadOzContainer(
        container: containerBytes,
        contentType: "application/octet-stream",
      );

Do not call OZSDK.analyze.

Your backend submits the container to Oz API in a single synchronous POST request.

Endpoint (Instant API):

POST {{host}}/api/instant/folders/

Endpoint (Full API):

POST {{host}}/api/folders/

Headers:

• Content-Type: application/octet-stream (mandatory).

• X-Forensic-Access-Token: {{access_token}}. (optional, depends on installation settings).

Request body: the raw container bytes – no JSON envelope, no multipart, no base64 wrapping.

Request (Instant API):

curl -X POST '{{host}}/api/instant/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'

Request (Full API):

curl -X POST '{{host}}/api/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'

On success: HTTP 201 with a JSON folder object describing the result. Check Step 7.

On container-level error: HTTP 400 – see Exceptions.

This guide covers the Liveness analysis. To perform a Face Matching analysis within the OzCapsula flow, see How to Perform a Face Matching Analysis within OzCapsula Flow.

7

(your code) Handle the response

Your backend now has the response – a JSON folder object describing the result.

Make the accept/reject decision using only these two top-level fields:

$.resolution_status   // "FINISHED" – analyses completed; "FAILED" – error during analysis processing
$.system_resolution   // "SUCCESS", "DECLINED", or "FAILED"

Interpret system_resolution:

• SUCCESS – all checks passed; accept the user.

• DECLINED – one or more checks failed; reject the user.

• FAILED – a system error prevented at least one analysis from completing; do not treat as accept or reject.

For per-analysis verdicts (for example, to know whether liveness passed but biometry failed), read $.analyses[*].resolution_status with the values described above.

Checklist

• iOS, Android, Flutter SDK 10.0.0+, Oz API 6.6.1+.

• Step 2 license init runs once per app launch.

• Step 2 also connects the telemetry receiver with the event host + service token.

• Step 3 obtains a fresh session_token from your backend before every capture.

• Step 4 passes that session_token into createMediaCaptureScreen(...).

• Step 5 returns a DataContainer; no attempt is made to decode/inspect images on-device.

• Step 6 uploads the container to your own backend as application/octet-stream, and your backend submits it to POST {{host}}/api/instant/folders/ (Instant API) or POST {{host}}/api/folders/ (Full API).

• The analysis is never run directly from the mobile SDK.

• The accept/reject decision uses only resolution_status and system_resolution.

• session_token is never cached, reused, or shared across sessions/users.

---

With these steps, you are done with basic integration of Mobile SDKs. You will be able to access recorded media and analysis results in Web Console via browser or programmatically via API.

In developer guides, you can also find instructions for customizing the SDK look-and-feel and access the full list of our Mobile SDK methods. Check out the table below:

Android sample app source code	iOS sample app source code	Flutter sample app source code
Android SDK Developer Guide	iOS SDK Developer Guide	Flutter SDK Developer Guide
Demo app in PlayMarket	Demo app in TestFlight