> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/sdk-integration-flows-on-premise/integration-flow-examples-for-web-sdk.md). # 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:
ModeAPIWho submits to the APIPersistenceBest-frame source
capture (default)Instant (stateless)Customer BackendS3 only (optional)Base64 from response, or S3
liteInstant (stateless)Web SDK AdapterS3 only (optional)Base64 from response, or S3
normalFull, persistent (stateful)Web SDK AdapterFolder, media, and results stored and retrievableBase64 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) | | S3 | Object storage for request data and images | Customer | | Oz Telemetry Receiver | Cloud-hosted [telemetry](/oz-knowledge/other/faq.md#what-is-telemetry-and-why-should-i-use-it) 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 1. **EndUser** opens the application or page. 2. **Customer APP** requests Web SDK static (JS, CSS) and dynamic resources from the **Web SDK Adapter** and downloads them. 3. *(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**. 4. **Customer APP** calls `OzLiveness.open()` on the **Web SDK Plugin**, passing the `session_token`. 5. *(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. 6. **Web SDK Plugin** calls the **Web SDK Adapter** to initialize a session and receives session data in response. 7. **Web SDK Plugin** displays the capture screen to the **EndUser**. ### Liveness / Analysis Check 1. **EndUser** starts the capture process (video). 2. **Web SDK Plugin** returns the captured data (as a multipart request or a binary OzCapsula container) to the **Customer APP** (not to the Adapter). 3. **Customer APP** sends the captured data to the **Customer Backend**. 4. **Customer Backend** forwards an analysis request to **Oz Instant API**. 5. *(Optional, recommended – requires configuration)* **Oz Instant API** stores analysis data (images, metadata) in **S3**. 6. **Oz Instant API** returns the analysis result to the **Customer Backend**. 7. *(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](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/liveness/best-shot.md), or * Retrieving the image from **S3** for internal usage. 8. **Customer Backend** returns the analysis result to the **Customer APP**. 9. **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 1. **EndUser** opens the application or page. 2. **Customer APP** requests Web SDK static (JS, CSS) and dynamic resources from the **Web SDK Adapter** and downloads them. 3. *(Optional, recommended – OzCapsula)* The `session_token` is obtained as described in [Session token](#session-token-ozcapsula). 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"`). 4. **Customer APP** calls `OzLiveness.open()` on the **Web SDK Plugin**, passing the `session_token` if it was obtained in step 3. 5. *(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. 6. **Web SDK Plugin** calls the **Web SDK Adapter** to initialize a session and receives session data in response. 7. **Web SDK Plugin** displays the capture screen to the **EndUser**. ### Liveness Check 1. **EndUser** starts the capture process (video). 2. **Web SDK Plugin** sends the captured data (as a multipart request or a binary OzCapsula container) to the **Web SDK Adapter**. 3. **Web SDK Adapter** forwards an analysis request to **Oz Instant API**. 4. *(Optional, recommended – requires configuration)* **Oz Instant API** stores request data (images, metadata) in **S3**. 5. **Oz Instant API** returns the liveness result to the **Web SDK Adapter**. 6. **Web SDK Adapter** passes the result to the **Web SDK Plugin**. 7. **Web SDK Plugin** returns the liveness result to the **Customer APP**. 8. *(Optional – additional internal check routine)* **Customer APP** queries its own **Customer Backend**, which retrieves data/images from **S3** for internal verification purposes. 9. **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 1. **EndUser** opens the application or page. 2. **Customer APP** requests Web SDK static (JS, CSS) and dynamic resources from the **Web SDK Adapter** and downloads them. 3. *(Optional, recommended – OzCapsula)* The `session_token` is obtained as described in [Session token](#session-token-ozcapsula). 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"`). 4. **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: ```javascript OzLiveness.open({ ... meta: { 'end_user_id': '', 'transaction_id': '' } }); ``` 5. *(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. 6. **Web SDK Plugin** calls the **Web SDK Adapter** to initialize a session and receives session data in response. 7. **Web SDK Plugin** displays the capture screen to the **EndUser**. ### Liveness / Analysis Check 1. **EndUser** starts the capture process (video). 2. **Web SDK Plugin** sends the captured data (as a multipart request or a binary OzCapsula container) to the **Web SDK Adapter**. 3. **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. 4. **Oz API** runs the analyses asynchronously and persists the folder, media, and results. 5. When the analysis is done, the **Web SDK Plugin** fires the `on_complete` callback to notify the **Customer APP**. 6. **Customer APP** calls the **Customer Backend**, passing the `transaction_id`. 7. **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`. 8. **Customer Backend** makes all further process-flow decisions. 9. *(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). 10. **Customer Backend** returns the result to the **Customer APP**. 11. **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](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/using-a-webhook-to-get-results.md) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/sdk-integration-flows-on-premise/integration-flow-examples-for-web-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.