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.

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
capture	Full, persistent (stateful)	Customer Backend	Folder, media, and results stored and retrievable	Base64 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 retrievable	Base64 from response, or persisted Oz API media

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 mobile application	–
Customer Mobile APP	Customer-facing mobile application	Customer
Customer Backend	Customer's own backend service	Customer
Oz Mobile SDK (embedded library)	Embedded liveness capture library integrated into the mobile app	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 persisting analysis data	Customer
Oz Telemetry Receiver	Cloud-hosted telemetry collection service	Oz (cloud)
api.cryptlex.com	Third-party licensing service used by Oz for Mobile SDK license validation	Third-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.

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

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.

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