Integration Flow Examples for Web SDK

The Web SDK runs in the browser and handles media capture. This guide covers both API modes and, within Instant API, both integration topologies. The flows differ along two axes: which Oz API submits the analysis (Instant, stateless vs. full, persistent) and who submits the request (the Customer Backend or the Web SDK Adapter).

The recommended default is capture mode with Instant API: the Customer Backend submits the analysis request, giving you full control over data flow and storage, and the stateless Instant API keeps no data server-side. The other modes are documented below as alternatives.

The architecture configuration key selects the topology:

Mode

API

Who submits to the API

Persistence

Best-frame source

capture (default)

Instant (stateless)

Customer Backend

S3 only (optional)

Base64 from response, or S3

lite

Instant (stateless)

Web SDK Adapter

S3 only (optional)

Base64 from response, or S3

normal

Full, persistent (stateful)

Web SDK Adapter

Folder, media, and results stored and retrievable

Base64 from response, or persisted Oz API media

normal is the default value of the architecture key itself; set architecture to capture for the integration described here as recommended.

Participants

These participants appear across the flows below. Each flow reuses these definitions and notes any deviations.

Participant

Description

Owner

EndUser

End user interacting with the application

–

Customer APP

Customer-facing frontend application

Customer

Customer Backend

Customer's own backend service

Customer

Oz Web SDK Plugin (Frontend)

Frontend capture component, dynamically generated by the Web SDK Adapter on user request

Oz (deployed on customer side)

Oz Web SDK Adapter (Backend)

Backend component of the Web SDK

Oz (deployed on customer side)

Oz API

Full, persistent (stateful) analysis service for liveness/biometric checks. Creates folders and stores media, analyses, and results.

Oz (deployed on customer side)

Oz Instant API

Stateless analysis service for liveness/biometric checks. No database; S3 is the only persistence option.

Oz (deployed on customer side)

Object storage for request data and images

Customer

Oz Telemetry Receiver

Cloud-hosted telemetry collection service

Oz (cloud)

Session token (OzCapsula)

OzCapsula requires a session_token. It is requested from Oz API at GET /api/authorize/session_token (or, with API 6.6.2 and newer, POST as an alternative) – the same call and the same result regardless of API mode (full or Instant). When used, the session_token is embedded into the container and validated server-side by Oz API.

The token is time-limited (default: 900 seconds for API Full, 120 seconds for API Instant). It should be requested each time the Customer App calls Oz Web SDK: right after the SDK call and as close as possible to the moment the user starts the capture. Requesting it too early risks expiration before the analysis request reaches the API, resulting in a rejected container. The session_token is mandatory when OzCapsula is used.

Two paths obtain it, selected by api_use_session_token:

api – the Web SDK fetches the session_token itself (for testing environment only; for production, use api_use_session_token: "client").
client – the Customer Backend fetches the session_token and passes it to the Customer APP.

The `capture` mode (Instant API) – recommended

The recommended default. The Web SDK Plugin only performs capture and returns the raw captured data to the Customer APP, which sends it to Oz Instant API through the Customer Backend. This gives the customer full control over the analysis request flow and data handling, and the stateless Instant API keeps no data server-side. The token is acquired through the Customer Backend.

Sequence diagram

Session Initialization

EndUser opens the application or page.
Customer APP requests Web SDK static (JS, CSS) and dynamic resources from the Web SDK Adapter and downloads them.
(Optional, recommended – OzCapsula) Customer APP requests a session token from the Customer Backend, which requests it from Oz API and returns the session_token to the Customer APP.
Customer APP calls OzLiveness.open() on the Web SDK Plugin, passing the session_token.
(Optional, enabled by default) The Web SDK Plugin begins sending recurring telemetry data to the Web SDK Adapter for the duration of the user session.
Web SDK Plugin calls the Web SDK Adapter to initialize a session and receives session data in response.
Web SDK Plugin displays the capture screen to the EndUser.

Liveness / Analysis Check

EndUser starts the capture process (video).
Web SDK Plugin returns the captured data (as a multipart request or a binary OzCapsula container) to the Customer APP (not to the Adapter).
Customer APP sends the captured data to the Customer Backend.
Customer Backend forwards an analysis request to Oz Instant API.
(Optional, recommended – requires configuration) Oz Instant API stores analysis data (images, metadata) in S3.
Oz Instant API returns the analysis result to the Customer Backend.
(Optional – saving best frame for internal usage) Customer Backend obtains the best-frame image by one of two methods:
- Extracting and saving the base64-encoded image directly from the API response, or
- Retrieving the image from S3 for internal usage.
Customer Backend returns the analysis result to the Customer APP.
Customer APP displays the analysis result to the EndUser.

Telemetry Finalization

After the user session ends, the Web SDK Adapter sends the accumulated telemetry data to the Oz Telemetry Receiver (Oz cloud service). This step is optional but enabled by default.

Key Points

Web SDK is delivered as a single Docker image containing both the Plugin (frontend) and the Adapter (backend).
In capture mode, the Web SDK only handles capture – all analysis requests go through the Customer Backend, giving the customer full control over data flow and storage.
Service token acquisition goes through the Customer Backend (recommended).
Oz Instant API is a separate stateless service responsible for biometric analysis.
Best-frame retrieval supports two options: decoding from the API response (base64) or fetching from S3.
Telemetry collection is optional (enabled by default) and sends anonymized usage data to Oz cloud.
S3 storage is optional but recommended for persisting analysis data and enabling downstream retrieval by the customer's systems.

The `lite` mode (Instant API)

An alternative to capture on the same stateless Instant API. Differs from capture in who submits the analysis: the Web SDK Adapter submits to Oz Instant API directly and returns the final result, instead of routing through the Customer Backend. Token handling follows api_use_session_token (the Web SDK or the Customer APP obtains the token).

Sequence diagram

Session Initialization

EndUser opens the application or page.
Customer APP requests Web SDK static (JS, CSS) and dynamic resources from the Web SDK Adapter and downloads them.
(Optional, recommended – OzCapsula) The session_token is obtained as described in Session token. With api_use_session_token: "client", the Customer APP requests it from the Customer Backend, which requests it from Oz API and returns it. With api_use_session_token: "api", the Web SDK fetches it and this step is skipped _{(for testing environment only; for production, use}_{api_use_session_token: "client"}₎.
Customer APP calls OzLiveness.open() on the Web SDK Plugin, passing the session_token if it was obtained in step 3.
(Optional, enabled by default, requires configuration) The Web SDK Plugin begins sending recurring telemetry data to the Web SDK Adapter for the duration of the user session.
Web SDK Plugin calls the Web SDK Adapter to initialize a session and receives session data in response.
Web SDK Plugin displays the capture screen to the EndUser.

Liveness Check

EndUser starts the capture process (video).
Web SDK Plugin sends the captured data (as a multipart request or a binary OzCapsula container) to the Web SDK Adapter.
Web SDK Adapter forwards an analysis request to Oz Instant API.
(Optional, recommended – requires configuration) Oz Instant API stores request data (images, metadata) in S3.
Oz Instant API returns the liveness result to the Web SDK Adapter.
Web SDK Adapter passes the result to the Web SDK Plugin.
Web SDK Plugin returns the liveness result to the Customer APP.
(Optional – additional internal check routine) Customer APP queries its own Customer Backend, which retrieves data/images from S3 for internal verification purposes.
Customer APP displays the liveness result to the EndUser.

Telemetry Finalization

After the user session ends, the Web SDK Adapter sends the accumulated telemetry data to the Oz Telemetry Receiver (Oz cloud service). This step is optional but enabled by default.

Key Points

Web SDK is delivered as a single Docker image containing both the Plugin (frontend) and the Adapter (backend).
OzCapsula is supported (use_wasm_container: true); token handling follows api_use_session_token.
Service token acquisition goes through the Customer Backend (recommended).
Oz Instant API is a separate stateless service responsible for biometric analysis.
Telemetry collection is optional (enabled by default) and sends anonymized usage data to Oz cloud.
S3 storage is optional but recommended for persisting request data and enabling downstream verification by the customer's own systems.

The `normal` mode (Full API)

An alternative that targets the full, persistent (stateful) Oz API instead of Instant API. Like lite, the Web SDK Adapter submits the request and returns the final result; unlike the Instant modes, the Oz API creates a folder and stores the media, analyses, and results, which remain retrievable afterwards.

Sequence diagram

Session Initialization

EndUser opens the application or page.
Customer APP requests Web SDK static (JS, CSS) and dynamic resources from the Web SDK Adapter and downloads them.
(Optional, recommended – OzCapsula) The session_token is obtained as described in Session token. With api_use_session_token: "client", the Customer APP requests it from the Customer Backend, which requests it from Oz API and returns it. With api_use_session_token: "api", the Web SDK fetches it and this step is skipped _{(for testing environment only; for production, use}_{api_use_session_token: "client"}₎.
Customer APP calls OzLiveness.open() on the Web SDK Plugin, passing the session_token if it was obtained in step 3, and a unique transaction_id (and optionally end_user_id) in meta so the folder can be found from the back end afterwards:
```
   OzLiveness.open({
     ...
     meta: {
       'end_user_id': '',
       'transaction_id': ''
     }
   });
```
(Optional, enabled by default) The Web SDK Plugin begins sending recurring telemetry data to the Web SDK Adapter for the duration of the user session.
Web SDK Plugin calls the Web SDK Adapter to initialize a session and receives session data in response.
Web SDK Plugin displays the capture screen to the EndUser.

Liveness / Analysis Check

EndUser starts the capture process (video).
Web SDK Plugin sends the captured data (as a multipart request or a binary OzCapsula container) to the Web SDK Adapter.
Web SDK uploads the captured data to the Oz API automatically – the Oz API creates a folder (tagged with the transaction_id supplied in meta), stores the tagged media, and launches the requested analyses.
Oz API runs the analyses asynchronously and persists the folder, media, and results.
When the analysis is done, the Web SDK Plugin fires the on_complete callback to notify the Customer APP.
Customer APP calls the Customer Backend, passing the transaction_id.
Customer Backend retrieves the result directly from Oz API using the Folder LIST method, matching on the transaction_id folder metadata: /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true. To speed up the request, add a time filter: /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true&time_created.min=([CURRENT_TIME]-1hour). In the response, it finds the analysis results and folder_id.
Customer Backend makes all further process-flow decisions.
(Optional – internal use) Customer Backend obtains the best-frame image either by decoding the base64 image from the response (analyses[].results_media[].output_images[].image_b64) or by retrieving the persisted media from the Oz API (original_url is a real URL in the full API).
Customer Backend returns the result to the Customer APP.
Customer APP displays the analysis result to the EndUser.

Telemetry Finalization

After the user session ends, the Web SDK Adapter sends the accumulated telemetry data to the Oz Telemetry Receiver (Oz cloud service). This step is optional but enabled by default.

Key Points

Web SDK is delivered as a single Docker image containing both the Plugin (frontend) and the Adapter (backend).
In normal mode, the Web SDK uploads to the Oz API automatically after capture – the upload path does not go through the Customer Backend.
OzCapsula is supported (use_wasm_container: true) and uploads the container to the full Oz API. OzCapsula is optional; without it, regular captured media is uploaded.
Service token acquisition goes through the Customer Backend (recommended).
Oz API here is the full, persistent (stateful) service: the folder, media, and results are stored and remain retrievable afterwards.
Analyses run asynchronously. For security, the Customer Backend retrieves results directly from Oz API (via the Folder LIST method, matched on the transaction_id folder metadata) and makes all process-flow decisions on the back end, rather than acting on the result in the browser context. Polling or a resolution_endpoint webhook can be used to determine when results are ready.
Best-frame retrieval supports two options: decoding from the API response (base64) or retrieving the persisted media from the Oz API.
Telemetry collection is optional (enabled by default) and sends anonymized usage data to Oz cloud.

PreviousIntegration Flow Examples for Mobile SDKs NextMigration Guides

Last updated 22 days ago

Was this helpful?

Participants

Session token (OzCapsula)

The capture mode (Instant API) – recommended

Session Initialization

Liveness / Analysis Check

Telemetry Finalization

Key Points

The lite mode (Instant API)

Session Initialization

Liveness Check

Telemetry Finalization

Key Points

The normal mode (Full API)

Session Initialization

Liveness / Analysis Check

Telemetry Finalization

Key Points

The `capture` mode (Instant API) – recommended

The `lite` mode (Instant API)

The `normal` mode (Full API)