Migration to OzCapsula

This guide describes the migration to the latest OzCapsula architecture: the approach where you use an encrypted to securely transmit data between frontend and backend.

Component Version Requirements

Before starting the migration, ensure that all components are updated to the minimum required versions:

• API: 6.4.1.

• Web SDK: 1.9.2.

• Native SDKs (iOS / Android): 8.22.

Older versions are not compatible with the new capture and analysis flow.

Authentication Changes

All capture sessions now require a session_token issued by the backend.

• The token must be obtained before starting video capture.

• It is tied to the current session and the specific container.

• The token has a limited lifetime.

Migration actions

• Implement a backend call to obtain session_token.

• Pass the token explicitly when creating the capture screen.

Flow Changes

Before Container (Legacy Flow)

1. You launch media capture.

2. Media is captured.

3. Media along with required data is sent to Oz API (using your backend as intermediate if needed).

With Container (New Flow)

1. You request session_token from backend.

2. You put additional data like metadata (if needed) into container and launch video capture with session_token.

3. SDK captures media, packages it into container, and returns a Media Container.

4. Media container is sent to Oz API (using your backend as intermediate if needed).

Migration actions

API

• Upgrade to v6.4.1-40 or higher.

• Switch Content-Type of data you send to application/octet-stream.

• For Instant API, obtain private and public keys as described here.

Web SDK

• Upgrade to v1.9.2 or higher.

• Ensure backend supports session_token.

• In the configuration file, set use_wasm_container to true and api_use_session_token to api or client (please refer to this article for details).

• Update initialization to pass token explicitly.

• If you use the capture architecture type, ensure you receive and send to your backend and then to us a blob object (application/octet-stream).

Mobile SDKs

• Upgrade to v8.22 or higher.

• Ensure backend supports session_token.

• Implement new interfaces as described below.

Android

1

Launching Capture Screen

Container flow

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

Old flow

2

Delegate

Container flow

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

Old flow

3

Launching Analysis

Container flow

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

    AnalysisRequest.Builder()
        .addContainer(container)
        .build()
        .run(
            { result ->
                val isSuccess = result.analysisResults.all { it.resolution == Resolution.SUCCESS }
            },
            { /* show error */ },
            { /* update status */ },
        )
}

Old flow

iOS

1

Launching Capture Screen

Container flow

getSessionToken() { sessionToken in
            DispatchQueue.main.async {
                do {
                    let action:OZVerificationMovement = .selfie
                    let mediaRequest = MediaRequest.action(action)
                    let profile = AnalysisProfile(mediaList: [mediaRequest],
                                                  type: .quality,
                                                  params: [:] )
                    let request = CaptureRequest(analysisProfileList: [profile], cameraPosition: .front)
                    let ozLivenessVC = try OZSDK.createMediaCaptureScreen(self, request, sessionToken: sessionToken)
                    self.present(ozLivenessVC, animated: true)
                } catch let error {
                    print(error.localizedDescription)
                }
            }
        }

Old flow

2

Delegate

Container flow

extension ViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
    }
    
    func onError(status: OZVerificationStatus?) {
    }
}

Old flow

3

Launching Analysis

Container flow

func onResult(container: DataContainer) {
  let analysisRequest = AnalysisRequestBuilder()
  analysisRequest.addContainer(container)
  analysisRequest.run(
            statusHandler: { status in
            },
            errorHandler: { error in
            }
        ) { result in
            
        }
}

Old flow

Migration Checklist

• API is updated to 6.4.1 or newer, with session_token supported.

  • Content-Type is changed to application/octet-stream.

  • For Instant API, private and public keys are obtained.

• Mobile SDKs are updated to 8.22 or newer.

  • New public interface is implemented: createMediaCaptureScreen with CaptureRequest.

• Web SDK is updated to 1.9.2 or newer.

  • use_wasm_container is set to true.

  • api_use_session_token is set to api or client.

  • if api_use_session_token = client, session_token is passed in open.options().

For best results, migrate all components simultaneously and avoid partial upgrades.