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

OzCapsula in Web SDK requires API 6.6.1 and newer.

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	client	Defines the retrieval of session token via your backend

Session token

In configuration file, set api_use_session_token: "client" for your backend to obtain 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.

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.

Please note: currently, the container works with single request mode only.

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