> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/setup/ios/configuration/starting-liveness-flow.md).

# Starting Liveness Flow

The Liveness flow has three steps:

1. **`setup`** : give the SDK your credentials and options, once.
2. **`prewarm()`** : optionally request the liveness session while the user is still on the previous screen.
3. **`startSDK`** : present the capture screen and receive the result through the delegate.

{% hint style="warning" %}
**Breaking in 3.0.0:** configuration moved from `startSDK` to `setup`. The old `startSDK(viewController:mobileToken:personId:…)` overload was removed — existing calls will not compile. See the [migration guide](https://docs.caf.io/pages/c80f05478a4841dc79a896cf92c619e4a56f606d#v3.0.0).
{% endhint %}

## Create the SDK instance

Instantiate `CafFaceLivenessLiteSDK` directly and set its `delegate`. Behavior is configured via the constructor and the `setup` parameters.

```swift
CafFaceLivenessLiteSDK(enableSecurity: Bool = true)
```

| Parameter        | Type | Required | Description                                                                                                                                                                                                                                           |
| ---------------- | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enableSecurity` | Bool | No       | Enables security monitoring: jailbreak detection, instrumentation detection, and dylib monitoring. Default: `true`. Disable only in automated testing environments. See [Security Checks](https://docs.caf.io/sdk-lite/setup/ios/security-checks.md). |

## Configure

Call `setup` before starting. It only stores your configuration — it performs no network request and presents nothing.

| Parameter                  | Type                   | Required | Description                                                                                                                                                                  |
| -------------------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mobileToken`              | String                 | Yes      | The `sessionToken` your backend requested for this attempt. See [Backend Setup](https://docs.caf.io/sdk-lite/setup/backend/setup.md)                                         |
| `personId`                 | String                 | Yes      | User identifier                                                                                                                                                              |
| `customLocalization`       | String?                | No       | Strings table name for custom localization (e.g., "stringsBundle")                                                                                                           |
| `customLocalizationBundle` | Bundle?                | No       | Bundle containing the custom strings table                                                                                                                                   |
| `uiCustomization`          | CerttaUiCustomization? | No       | Visual branding for the liveness screen (default: `nil`, no customization). See [UI Customization](https://docs.caf.io/sdk-lite/setup/ios/configuration/ui-customization.md) |
| `environment`              | CafEnvironment (enum)  | No       | `.dev`, `.beta`, `.prod` (default: `.prod`)                                                                                                                                  |
| `loading`                  | Bool                   | No       | Show SDK loading screen (default: `true`)                                                                                                                                    |

### Custom localization with a framework bundle

`customLocalization` is the strings table name (omit the `.strings` extension). When custom `Localizable.strings` ship inside a framework (or another non-main bundle), pass both the table name and the bundle:

```swift
sdk.setup(
    mobileToken: "your_mobile_token",
    personId: "your_person_id",
    customLocalization: "Localizable",
    customLocalizationBundle: Bundle(for: CafFaceLivenessLiteSDK.self),
    environment: .prod,
    loading: true
)
sdk.startSDK(viewController: self)
```

Localization reference: [iProov Localization](https://github.com/iProov/ios/wiki/Localization)

### UI customization

To brand the liveness screen — header bar, guidance prompt, area around the face oval and font — pass a `CerttaUiCustomization` through the `uiCustomization` parameter of `setup`. Available from **2.1.0** and fully optional. See [UI Customization](https://docs.caf.io/sdk-lite/setup/ios/configuration/ui-customization.md).

## Pre-warm

`prewarm()` performs the session request ahead of time so `startSDK` can open the camera without waiting on the network. Call it at any point where the user is already occupied — an instructions screen, a consent step, a form — and the round trip overlaps with their reading time instead of adding to it.

```swift
sdk.setup(mobileToken: "your_mobile_token", personId: "your_person_id")
sdk.prewarm()                       // e.g. when the instructions screen appears
// … user reads the instructions …
sdk.startSDK(viewController: self)  // consumes the prewarmed session
```

`prewarm()` returns immediately and reports nothing: it has no completion handler and never invokes the delegate. It is safe to call from any thread and safe to call more than once — while a request is in flight, or while a valid session is already cached, it does nothing rather than requesting a second session. It is a no-op before `setup`.

{% hint style="info" %}
**Prewarming is always optional and can never break a capture.** If no valid session is available when `startSDK` runs — because prewarming failed, was never called, or the cached session is no longer usable — the SDK silently falls back to requesting the session inline, exactly as it did before 3.0.0.
{% endhint %}

A prewarmed session is discarded when:

| Condition                          | Detail                                                                                                     |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| It is older than **90 seconds**    | Start the capture within that window to benefit from prewarming                                            |
| Credentials or environment changed | A later `setup` with a different `mobileToken`, `personId` or `environment` invalidates it                 |
| The app was sent to the background | The cached session and the stored credentials are cleared                                                  |
| It was already used                | Each prewarmed session is consumed by a single `startSDK` call; call `prewarm()` again for another capture |

Two behaviors worth noting when you integrate:

* **No `loading()` / `loaded()` pair is emitted for the session request on the prewarmed path**, since there is nothing to wait for. From **3.1.0** none is emitted after the capture either, because the result is delivered immediately. Do not rely on `loading()` as a signal that capture has begun.
* `prewarm()` stores the mobile token and person ID in the keychain before issuing the request, because the request is authenticated from the keychain. They are removed if prewarming fails or the app is backgrounded.

## Start Liveness

`startSDK` presents the capture screen using the configuration supplied to `setup`. It takes only the presenting view controller. Call it on the main thread.

| Parameter        | Type             | Required | Description                    |
| ---------------- | ---------------- | -------- | ------------------------------ |
| `viewController` | UIViewController | Yes      | The presenting view controller |

Calling `startSDK` without a prior `setup` does not present anything — it reports `didFinishWithError(type: .invalidOptionsException, description:)` instead. See [Error Handling](https://docs.caf.io/sdk-lite/error-handling/ios/error-handling.md#invalidoptionsexception).

`startSDK` checks camera access before any network request. If the user has not decided yet, the system prompt is shown; if access is denied, the SDK reports `didFinishWithError(type: .cameraPermission, description:)`.

Calling `startSDK` while a capture is already running is ignored — nothing is presented and no delegate method is called.

{% hint style="warning" %}
**Breaking in 2.0.0:** `executeFaceAuth` was removed. The SDK starts an async transaction and returns only `signedResponse`. Retrieve the final liveness outcome from your backend.
{% endhint %}

## Complete example

```swift
import UIKit
import CafFaceLivenessLite

final class MainViewController: UIViewController {
    private let sdk = CafFaceLivenessLiteSDK(enableSecurity: true)

    override func viewDidLoad() {
        super.viewDidLoad()
        sdk.delegate = self

        sdk.setup(
            mobileToken: "mobileToken",
            personId: "personId",
            customLocalization: nil,
            customLocalizationBundle: nil,
            environment: .prod,
            loading: true
        )
        // Optional: overlap the session request with whatever the user does next
        sdk.prewarm()

        let startButton = UIButton(type: .system)
        startButton.setTitle("Start Liveness Lite", for: .normal)
        startButton.addTarget(self, action: #selector(startLivenessLite), for: .touchUpInside)
        view.addSubview(startButton)
        // Layout omitted
    }

    @objc private func startLivenessLite() {
        sdk.startSDK(viewController: self)
    }
}

extension MainViewController: CafFaceLivenessLiteDelegate {
    func didFinishWithSuccess(livenessResult: CafFaceLivenessLiteResult) {
        // Opaque JWT from async route — resolve final result on your backend
        print("Success: \(livenessResult.signedResponse ?? "-")")
    }

    func didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?) {
        print("Failure: type=\(type) desc=\(description ?? "-") signed=\(signedResponse ?? "-")")
    }

    func didFinishWithError(type: CafErrorType, description: String) {
        print("Error: type=\(type) desc=\(description)")
    }

    func cancelled() { print("Cancelled") }
    func loading() { print("Loading") }
    func loaded() { print("Loaded") }
}
```

## Events

The `CafFaceLivenessLiteDelegate` protocol handles key events during the liveness process. A run always ends with exactly one of `didFinishWithSuccess`, `didFinishWithFailure`, `didFinishWithError` or `cancelled()`.

| Event                                                                                       | Description                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `didFinishWithSuccess(livenessResult: CafFaceLivenessLiteResult)`                           | Called as soon as the capture completes; includes `signedResponse` JWT                                                                                                                                      |
| `didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?)` | Called when the capture completes without passing (lighting, alignment, etc.); always includes the session `signedResponse`. See [Mobile Failures](https://docs.caf.io/sdk-lite/failure-handling/mobile.md) |
| `didFinishWithError(type: CafErrorType, description: String)`                               | Called on execution error (permission, network, token, etc.). See [Error Handling](https://docs.caf.io/sdk-lite/error-handling/ios/error-handling.md) for each type and how to handle it                    |
| `cancelled()`                                                                               | User cancelled flow                                                                                                                                                                                         |
| `loading()`                                                                                 | SDK started waiting on the session request                                                                                                                                                                  |
| `loaded()`                                                                                  | SDK stopped waiting: emitted when the session request completes, and again when the flow ends, right after the final callback                                                                               |

For the fields and types returned by each callback, see [Result Reference](https://docs.caf.io/sdk-lite/setup/ios/result-reference.md).

`loading()` and `loaded()` are emitted whether or not the `loading` option of `setup` is enabled. That option only shows or hides the SDK's built-in loading screen.

From **3.0.0**, when a prewarmed session is consumed there is no session request to wait for, so no `loading()` / `loaded()` pair is emitted for that step.

From **3.1.0**, no `loading()` / `loaded()` pair is emitted after the capture either: the result is delivered the moment the capture completes, and the attempt is registered. On the prewarmed path this means the delegate may never receive `loading()` at all — do not rely on it as a signal that capture has begun.

{% hint style="warning" %}
Never decide the liveness outcome on the device. Your backend validates the `signedResponse` and retrieves the final result.
{% endhint %}

## Changing the user or credentials

You can call `setup` again to change any value — for example to switch `personId` between users. Doing so discards a previously prewarmed session whenever the credentials or environment differ. Call `prewarm()` again after reconfiguring.

## getVersion

```swift
let version = CafFaceLivenessLiteSDK.getVersion() // e.g. "7.8.0"
```

Available from **7.8.0**. Static method that returns the SDK version as a `String`. It needs no instance and no `setup`, which makes it handy for logging and support tickets.

## Next step

Forward the `signedResponse` to your backend, which validates it and retrieves the result: [Backend Setup](https://docs.caf.io/sdk-lite/setup/backend/setup.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/setup/ios/configuration/starting-liveness-flow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
