Migration to OzCapsula

This guide describes the migration to the latest OzCapsula architecture: the approach where you use an encrypted container 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.6.1.
Web SDK: 1.9.10.
Native SDKs (iOS / Android) and Flutter: 10.0.0.

We highly recommend using the latest versions of Oz software.

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

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

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)

You launch media capture.
Media is captured.
Media along with required data is sent to Oz API (using your backend as intermediate if needed).

With container (new flow)

You request session_token from backend.
You put additional data like metadata (if needed) into container and launch video capture with session_token.
SDK captures media, packages it into container, and returns an encrypted file.
The encrypted file is sent to Oz API (using your backend as intermediate if needed).

Migration actions

API

Upgrade to v6.6.1 or newer.
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.10 or newer.
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 v10.0.0 or newer.
Ensure backend supports session_token.
Implement new interfaces as described below.

Please note: do not use "_" (underscore) in file names for the container flow.

Android

Launching capture screen

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

Subscription to media

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

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

Launching analysis

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

private fun runAnalysis(media: List<OzAbstractMedia>?) {
    if (media.isNullOrEmpty()) return
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, media))
        .build()
        .run(
            { result ->
                val isSuccess = result.analysisResults.all { it.resolution == Resolution.SUCCESS }
            },
            { /* show error */ },
            { /* update status */ },
        )
}

iOS

Launching capture screen

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

do {
    let ozLivenessVC : UIViewController = try OZSDK.createVerificationVCWithDelegate(self, actions: .selfie)   
    self.present(ozLivenessVC, animated: true)
} catch let error {
    print(error.localizedDescription)
}

Subscription to media

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

Launching analysis

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

func onResult(results: [OZMedia]) {
        let analysisRequest = AnalysisRequestBuilder()
        let analysis = Analysis(media: results,
                                type: .quality,
                                mode: .serverBased,
                                params: nil)
        analysisRequest.addAnalysis(analysis)
        analysisRequest.run { status in
        } errorHandler: { error in
        } completionHandler: { results in
            
        }
    }

Flutter

Launching capture screen

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

Subscription to media

@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
  });
}

@override
void initState() {
  super.initState();
  _subscription = OZSDK.livenessResult.listen((result) {
    if (result is List) {
      final mediaList = result.toList().cast<Media>();
    }
  }, onError: (Object error) {
    // handle error, in most cases PlatformException
  });
}

Launching analysis

try {
  final Uint8List? containerBytes = await OZSDK.getContainerBytes(dataContainer);
  final List<RequestResult> analysisResult = await OZSDK.analyze(
      analysis: [],
      dataContainer: dataContainer,
    );
} catch (e) {
  _showErrorDialog(e);
}

Migration checklist

PreviousMigration Guides NextMigration from One Shot Gesture

Last updated 16 days ago

Was this helpful?