How to Integrate Oz Liveness into Your Web Application

Oz Liveness Web SDK implements the ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results. The SDK detects both presentation and injection attacks.

This guide walks you through your first liveness check using Web SDK and Oz API. Here, we cover the SaaS model.

The described flow combines:

• Capture mode – the Web SDK (or Mobile SDK) captures the Liveness video in the browser/app and the Client backend forwards it to Oz API. Capture results are not sent from the SDK straight to Oz API; the Client backend acts as an intermediary.

• OzCapsula – a proprietary encrypted binary container. The SDK packages the captured media into it; only Oz API can decrypt and process it. On the device it is an opaque blob – you cannot decode or inspect it, only forward it as-is.

Each step is marked:

• [Oz SDK] – call our SDK API.

• [Your code] – call your own backend or your own code.

{{host}} in the examples below is the base URL of your Oz API deployment, provided to you during deployment setup.

Requirements

Component	Minimum version
Oz API	6.6.1
Web SDK	1.9.10

You require a dedicated Web Adapter. Expand the section below if it has not yet been configured for your company.

How to obtain Web Adapter

Tell us domain names of the pages from which you are going to call Web SDK and email for admin access, e.g.:

Domain names from which Web SDK will be called: www.yourbrand.com www.yourbrand2.com Email for admin access: [e-mail]

In response, you’ll get URLs and credentials for further integration and usage. When using SaaS API, you get them from us:

Login: [e-mail] Password: … API: https://<link>.ozforensics.com/ Web Console: https://<link>.ozforensics.com Web Adapter: https://<link>.ozforensics.com/your_company_name/

These parameters are mandatory for OzCapsula to work. Define them in your API configuration file.

OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true

Instructions

1

(Oz SDK) Embed the plugin

Oz provides the plugin URL (served by the Oz-hosted adapter). Add it to your page:

<script src="https://path-to-websdk/plugin_liveness.php"></script>

2

(your code) Get a session_token from your backend

OzCapsula uses a session token. The token is mandatory for OzCapsula.

Your backend requests a session token from Oz API. Request it before each capture session, as close to the moment the user starts capture as possible.

Endpoint:

GET {{host}}/api/authorize/session_token

Request:

curl --location -g '{{host}}/api/authorize/session_token' \
--header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings

The authorization mechanism for calls to Oz API (access_token) depends on your installation settings: when using Instant API, you can integrate it under your own authorization scheme. If access token is required in your case, please check Authentication. Never expose the access token in the browser. Also, please note that access and session token are different tokens issued for different purposes.

Response:

{
  "session_token": "<session_token>"
}

This token is short-lived (default lifetime: 900 seconds for API Full, 120 seconds for Instant API). Request one per capture session and pass it to the SDK immediately – do not cache or reuse tokens across sessions.

3

(Oz SDK) Launch the plugin with the session_token

OzLiveness.open({
  lang: 'en',
  action: ['video_selfie_blank'],  // passive liveness
  session_token: session_token,    // session_token from Step 2
  on_capture_complete: function (action, ozCapsula) {
    // ozCapsula = the OzCapsula container (Blob) — Step 4
    sendToYourBackend(ozCapsula);
  },
  on_error: function (err) { /* handle */ }
});

4

(Oz SDK) Get the OzCapsula container

When capture completes, the SDK fires the on_capture_complete callback. The container is delivered as the second argument – a Blob with MIME type application/octet-stream.

The container is an opaque encrypted blob. You cannot decode it, inspect it, or extract individual images / frames / metadata from it on the device. It must be forwarded as-is to your backend. If you need access to captured images (e.g., the best shot), retrieve them from the Oz API analysis response on the server side.

Upload it to your backend as application/octet-stream.

5

(your code) Send the container to Oz API

Your backend submits the container in a single synchronous POST request.

Endpoint (Instant API):

POST {{host}}/api/instant/folders/

Endpoint (Full API):

POST {{host}}/api/folders/

Headers:

• Content-Type: application/octet-stream (mandatory).

• X-Forensic-Access-Token: {{access_token}}. (optional, depends on installation settings).

Request body: the raw container bytes – no JSON envelope, no multipart, no base64 wrapping.

Request (Instant API):

curl -X POST '{{host}}/api/instant/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'

Request (Full API):

curl -X POST '{{host}}/api/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'

On success: HTTP 201 with a JSON folder object describing the result. Check Step 6.

On container-level error: HTTP 400 – see Exceptions.

This guide covers the Liveness analysis. To perform a Face Matching analysis within the OzCapsula flow, see How to Perform a Face Matching Analysis within OzCapsula Flow.

6

(your code) Handle the response

Your backend now has the response – a JSON folder object describing the result.

Make the accept/reject decision using only these two top-level fields:

$.resolution_status   // "FINISHED" – analyses completed; "FAILED" – error during analysis processing
$.system_resolution   // "SUCCESS", "DECLINED", or "FAILED"

Interpret system_resolution:

• SUCCESS – all checks passed; accept the user.

• DECLINED – one or more checks failed; reject the user.

• FAILED – a system error prevented at least one analysis from completing; do not treat as accept or reject.

For per-analysis verdicts (for example, to know whether liveness passed but biometry failed), read $.analyses[*].resolution_status with the values described above.

Checklist

• Web SDK 1.9.10+, Oz API 6.6.1+.

• Step 1 embeds the plugin from the Oz-provided URL.

• Step 2 obtains a fresh session_token from your backend before every capture.

• Step 3 passes that session_token into OzLiveness.open(...).

• Step 4 takes the container from the second argument of on_capture_complete; no attempt is made to decode/inspect it in the browser.

• Step 5 submits the container to POST {{host}}/api/instant/folders/ (Instant API) or POST {{host}}/api/folders/ (Full API) as raw bytes with Content-Type: application/octet-stream.

• The accept/reject decision uses only resolution_status and system_resolution.

• session_token is never cached, reused, or shared across sessions/users.

---

With these steps, you are done with basic integration of Web SDK into your web application. You will be able to access recorded media and analysis results in Web Console via browser or programmatically via API (please find the instructions here: retrieving an MP4 video, getting analysis results).

In the Web Plugin Developer Guide, you can find instructions for common next steps:

• Customizing plugin look-and-feel

• Adding custom language pack

• Tuning plugin behavior

• Plugin parameters and callbacks

• Security recommendations

Please find a sample for Oz Liveness Web SDK here. To make it work, replace <web-adapter-url> with the Web Adapter URL you've received from us.

For Angular and React, replace https://<link>.ozforensics.com in index.html.

• Angular sample

• React sample

• Vue sample

• Svelte sample