Using OzCapsula Data Container in Web SDK

In this mode, the SDK captures media from the user, packs all biometric and technical data into a container (application/octet-stream), and then either:

• uploads it directly to Oz API (architecture: normal for stateful API or lite for Instant), or

• returns it to your backend for forwarding (capture architecture).

Configuration Overview

When enabling container mode, the key parameters are:

Parameter	Value	Description
use_wasm_container	true	Enables data container generation
architecture	normal / lite/ capture	Defines who sends the data to Oz API (Web SDK or your backend)
api_use_session_token	api / client	Defines who retrieves the session token (Web SDK or your backend)

Session Token

api_use_session_token: "client"

In this mode, your backend obtains the session token before opening the Web SDK.

Steps:

1. Request a session token from Oz API:

curl --location '{{host}}/api/authorize/session_token' \
  -H 'X-Forensic-Access-Token: <YOUR_TOKEN>'

1. The response will contain a short-term session_token:

{
  "session_token": "eyJh..."
}

1. Pass this token to the Web SDK Plugin:

OzLiveness.open({
  session_token,
  // other open options
});

The session token is valid only for a few minutes and must be requested before each capture session.

api_use_session_token: "api"

In this mode, the SDK automatically retrieves the session token directly from Oz API. You don’t need to request or provide it manually.

Flow for Different Architectures

The flow is different depending on your architecture type.

architecture: "normal"

In this mode, the Web SDK automatically uploads the generated container to Oz API. You do not need to handle any upload manually.

architecture: "lite"

In this mode, the Web SDK automatically uploads the generated container to Oz API. You do not need to handle any upload manually.

architecture: "capture"

In this mode, Web SDK only captures and packs data, but does not send it to the Oz API.

Your backend is responsible for receiving the container and forwarding it to Oz API.

Flow:

1. Web SDK performs video capture and calls the on_capture_complete(result, container) callback, where the second argument (container) is a Blob object (application/octet-stream).

2. You send this blob to your backend.

3. Your backend sends it to Oz API using an HTTPS POST request.

Example request:

curl -X POST \
  '{{host}}/api/folders' \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-Forensic-Access-Token: <YOUR_TOKEN>' \
  --data-binary '@/path/to/container.dat'

The response will be similar to the one from the non-container flow.

Possible Errors

Error	Description
error_wasm_internal_failure_1	The device or browser used doesn’t support WASM
error_wasm_internal_failure_2	The device doesn’t have enough memory to proceed
error_wasm_internal_failure_3 error_wasm_internal_failure_4 error_wasm_internal_failure_5	SDK couldn’t generate the container. Try again
error_wasm_internal_failure_1000	Any other error not from the list above