> 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-mobile-sdks.md). # Integration Flow Examples for Mobile SDKs The Mobile SDK is an embedded library inside your mobile app that handles liveness capture. This guide covers both API modes and 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 Mobile SDK itself). The recommended default is **`capture` mode with Instant API**: the Mobile SDK only handles capture and 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. Capture mode can also target the full API; direct mode is documented below as an alternative.
ModeAPIWho submits to the APIPersistenceBest-frame source
capture (default)Instant (stateless)Customer BackendS3 only (optional)Base64 from response, or S3
captureFull, persistent (stateful)Customer BackendFolder, media, and results stored and retrievableBase64 from response, or persisted Oz API media
Direct (run, .useInstantMode(true))Instant (stateless)Mobile SDK (AnalysisRequest.run())S3 only (optional)Base64 from response, or S3
Direct (run)Full, persistent (stateful)Mobile SDK (AnalysisRequest.run())Folder, media, and results stored and retrievableBase64 from response, or persisted Oz API media
## Participants These participants appear across the flows below. Each flow reuses these definitions and notes any deviations.
ParticipantDescriptionOwner
EndUserEnd user interacting with the mobile application–
Customer Mobile APPCustomer-facing mobile applicationCustomer
Customer BackendCustomer's own backend serviceCustomer
Oz Mobile SDK (embedded library)Embedded liveness capture library integrated into the mobile appOz (deployed on customer side)
Oz APIFull, persistent (stateful) analysis service for liveness/biometric checks. Creates folders and stores media, analyses, and results.Oz (deployed on customer side)
Oz Instant APIStateless analysis service for liveness/biometric checks. No database; S3 is the only persistence option.Oz (deployed on customer side)
S3Object storage for persisting analysis dataCustomer
Oz Telemetry ReceiverCloud-hosted telemetry collection serviceOz (cloud)
api.cryptlex.comThird-party licensing service used by Oz for Mobile SDK license validationThird-party (Cryptlex)
## 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 Mobile App calls Oz Mobile SDK: right after the SDK initialization 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. ## The `capture` mode (Instant API) – recommended The recommended default. The Mobile SDK only handles capture and returns the captured data to your app; the analysis request is submitted through your own backend to Oz Instant API. This gives the customer full control over data flow and storage, and the stateless Instant API keeps no data server-side.
Sequence diagram
### Session Initialization 1. **EndUser** opens the app page that hosts liveness functionality. 2. **Customer Mobile APP** initializes the SDK by calling `OzLivenessSDK.init(License)`. 3. **Oz Mobile SDK** validates the license against the external **Cryptlex** licensing service (`api.cryptlex.com`). The license is bound to the app's bundle ID. 4. *(Optional, enabled by default – telemetry)* The app configures the telemetry channel via `OzLivenessSDK.setEventsConnection(telemetry_endpoint, credentials)`. The **Mobile SDK** verifies the connection to the **Oz Telemetry Receiver**. 5. *(Optional – OzCapsula only)* The app requests a session token from the **Customer Backend**, which requests a `session_token` from **Oz API** and returns it to the app. See [Session token](https://claude.ai/chat/426351c9-82f5-474a-ad62-54460833feed#session-token-ozcapsula). ### Liveness Capture and Analysis 1. **EndUser** taps "Start liveness". 2. **Customer Mobile APP** calls `OzLivenessSDK.createMediaCaptureScreen` on the **Mobile SDK**, passing the `session_token` (if OzCapsula is used). 3. **Mobile SDK** presents the liveness UI and captures the user's actions (video). 4. *(If OzCapsula is used)* The **Mobile SDK** packages the captured result into an OzCapsula container, ensuring data integrity and tamper protection. 5. **Mobile SDK** returns the captured data (raw or packaged container) to the **Customer Mobile APP**. 6. *(Optional)* The **Mobile SDK** finalizes and sends accumulated telemetry data to the **Oz Telemetry Receiver**. 7. **Customer Mobile APP** forwards the captured data to the **Customer Backend**. 8. **Customer Backend** sends an analysis request to **Oz Instant API**. 9. *(Optional, recommended – requires configuration)* **Oz Instant API** stores analysis data (images, metadata) in **S3**. 10. **Oz Instant API** returns the analysis result to the **Customer Backend**. 11. *(Optional – saving best frame for internal usage)* The **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. 12. **Customer Backend** returns the analysis result to the **Customer Mobile APP**. 13. **Customer Mobile APP** displays the liveness result to the **EndUser**. ### Key Points * **Oz Mobile SDK** is an **embedded library** within the customer's mobile app – not a standalone process. * In `capture` mode, the **Mobile SDK only handles capture** – all analysis requests go through the **Customer Backend**, giving the customer full control over data flow and storage. * **License validation** requires outbound network access from the mobile device to `api.cryptlex.com`. If this endpoint is unreachable, SDK initialization will fail. * **OzCapsula** is an optional secure data container that wraps the captured media, providing integrity validation and tamper protection. When used, the `session_token` is embedded into the container and validated server-side by Oz API. * **Telemetry** is initialized early (during session `init`) and finalized after capture completes, covering the full user session lifecycle. * **Oz Instant API** is a **stateless** service – there is no database. S3 is the only persistence option for post-factum data retrieval. * **Best-frame retrieval** supports two options: decoding from the API response (base64) or fetching from S3. ### Full API variant (capture mode) The same capture flow can target the full, persistent Oz API instead of Instant API. The Mobile SDK still only handles capture; the difference is on the Customer Backend side after it receives the captured data: 1. **Customer Backend** sends the captured media (with the required tags and metadata) to **Oz API** via `POST /api/folders/`. The folder is created automatically when the media and required information are sent. 2. **Customer Backend** initiates the analysis: `POST /api/folders/{folder_id}/analyses/`. To receive the result via [webhook](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/using-a-webhook-to-get-results.md), the backend includes the webhook in the payload at this step. 3. **Customer Backend** retrieves the result – either via the webhook, or by polling `GET /api/analyses/{analysis_id}` (by analysis) or `GET /api/folders/{folder_id}/analyses/` (by folder). Polling repeats until `resolution_status` reaches `FINISHED` or `FAILED`. 4. *(Optional – saving best frame for internal usage)* The **Customer Backend** obtains the best-frame image by retrieving the persisted media from the **Oz API**. Unlike the Instant variant, the Oz API creates a folder and stores the media, analyses, and results, which remain retrievable afterwards.
Sequence diagram
## Direct mode – method `run` An alternative in which the SDK is connected to Oz API (`setApiConnection`) and submits the analysis request itself via `AnalysisRequest.run()`, returning the result to your app – the analysis path does not go through the Customer Backend. With `.useInstantMode(true)` before `.run()`, it targets the stateless Instant API (the flow described here); without it, `run()` targets the full, persistent Oz API (see [Full API variant](https://claude.ai/chat/426351c9-82f5-474a-ad62-54460833feed#full-api-variant-direct-mode)). `run()` has two independent axes: the **input** is either `addAnalysis(...)` (captured media) or `addContainer(...)` (an OzCapsula container, which requires a `session_token` captured via `createMediaCaptureScreen(request, sessionToken)`); the **API target** is Instant API with `.useInstantMode(true)`, or the full Oz API by default. The axes are independent.
Sequence diagram
### Session Initialization 1. **EndUser** opens the app page that hosts liveness functionality. 2. **Customer Mobile APP** initializes the SDK by calling `OzLivenessSDK.init(License)`. 3. **Oz Mobile SDK** validates the license against the external **Cryptlex** licensing service (`api.cryptlex.com`). The license is bound to the app's bundle ID. 4. **Customer Mobile APP** establishes the API connection: `OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(host, token))` (or `fromCredentials(host, username, password)`). Call it **once** (for example, in the Application class) rather than at every screen open. 5. *(Optional, recommended – OzCapsula only)* **Customer Mobile APP** obtains a `session_token` from Oz API (directly, or via its **Customer Backend**) to be embedded in the container at capture time. See [Session token](https://claude.ai/chat/426351c9-82f5-474a-ad62-54460833feed#session-token-ozcapsula). 6. *(Optional, enabled by default – telemetry)* The app configures the telemetry channel (`OzLivenessSDK.setEventsConnection(...)`). The **Mobile SDK** verifies the connection to the **Oz Telemetry Receiver**. ### Liveness Capture and Analysis 1. **EndUser** taps "Start liveness". 2. **Customer Mobile APP** launches capture on the **Mobile SDK** – non-container: `OzLivenessSDK.createStartIntent(...)`; OzCapsula: `OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)`. 3. **Mobile SDK** presents the liveness UI and captures the user's actions (video). *(OzCapsula only)* It packages the result into an OzCapsula container. 4. **Mobile SDK** returns the result to the **Customer Mobile APP** through the result callback (captured media, or the OzCapsula container). 5. **Customer Mobile APP** builds the analysis request, calls `useInstantMode(true)` on it, and adds the analysis (captured media via `addAnalysis(...)`, or an OzCapsula container via `addContainer(...)`), then calls `run()`. 6. **Mobile SDK** submits the request directly to the Instant API (`POST /api/instant/folders/`), managing upload and result retrieval internally. 7. **Oz Instant API** runs the analyses without persisting any data. 8. **Oz Instant API** returns the analysis result to the **Mobile SDK**. 9. **Mobile SDK** returns the result to the **Customer Mobile APP** (via the `statusHandler` / `errorHandler` callbacks). 10. *(Optional)* The **Mobile SDK** finalizes and sends accumulated telemetry data to the **Oz Telemetry Receiver**. 11. **Customer Mobile APP** displays the liveness result to the **EndUser**. ### Telemetry Finalization The **Mobile SDK** finalizes and sends accumulated telemetry data to the **Oz Telemetry Receiver** after capture completes. This step is optional but enabled by default. ### Key Points * **Oz Mobile SDK** is an **embedded library** within the customer's mobile app – not a standalone process. * In direct mode, the **Mobile SDK submits the analysis request to Oz API itself** (via `AnalysisRequest.run()`) – the analysis path does **not** go through the Customer Backend. * `run()` works with OzCapsula (`addContainer`) as well as with plain captured media (`addAnalysis`). With OzCapsula, capture is done via `createMediaCaptureScreen(request, sessionToken)`; the `session_token` is mandatory. * `setApiConnection` is a precondition: it must complete successfully before invoking the capture method. It initiates a service call to Oz API, so call it once to avoid unnecessary server load. * **License validation** requires outbound network access from the mobile device to `api.cryptlex.com`. If this endpoint is unreachable, SDK initialization will fail. * **Oz Instant API** is a **stateless** service – there is no folder persistence. Best-frame retrieval is limited to decoding the base64 image from the response or fetching from S3 (if S3 storage is configured). * **Telemetry** collection is optional (enabled by default) and sends anonymized usage data to Oz cloud. ### Full API variant (direct mode) Without `.useInstantMode(true)`, the same `run()` call targets the full, persistent Oz API instead of Instant API. The SDK manages folder creation, upload, and result retrieval internally; the analyses run **asynchronously** and the Oz API persists the folder, media, and results, which remain retrievable afterwards. Best-frame retrieval supports two options: decoding the base64 image from the response (`analyses[].results_media[].output_images[].image_b64`) or retrieving the persisted media from the Oz API. All other steps are identical.
Sequence diagram
--- # 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-mobile-sdks.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.