> 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/sdk-lite-english-pt-br/configuracao/ios/configuration/starting-liveness-flow.md).

# Iniciando o fluxo de Liveness

O fluxo de Liveness tem três etapas:

1. **`setup`** : forneça ao SDK suas credenciais e opções, uma vez.
2. **`prewarm()`** : solicite opcionalmente a sessão de liveness enquanto o usuário ainda estiver na tela anterior.
3. **`startSDK`** : apresente a tela de captura e receba o resultado por meio do delegate.

{% hint style="warning" %}
**Mudanças na 3.0.0:** a configuração foi movida de `startSDK` para `setup`. O antigo `startSDK(viewController:mobileToken:personId:…)` sobrecargo foi removido — as chamadas existentes não compilarão. Veja o [guia de migração](https://docs.caf.io/pages/3bff86622c51e8dc1de0f8af79879d76d2241435#v3.0.0).
{% endhint %}

## Crie a instância do SDK

Instancie `CafFaceLivenessLiteSDK` diretamente e defina seu `delegate`. O comportamento é configurado pelo construtor e pelos `setup` parâmetros.

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

| Parâmetro        | Tipo | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                |
| ---------------- | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enableSecurity` | Bool | Não         | Habilita o monitoramento de segurança: detecção de jailbreak, detecção de instrumentação e monitoramento de dylib. Padrão: `verdadeiro`. Desative somente em ambientes de teste automatizado. Veja [Verificações de Segurança](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md). |

## Configurar

Chame `setup` antes de iniciar. Ele apenas armazena sua configuração — não realiza nenhuma solicitação de rede e não apresenta nada.

| Parâmetro                  | Tipo                   | Obrigatório | Descrição                                                                                                                                                                                                          |
| -------------------------- | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mobileToken`              | String                 | Sim         | O `sessionToken` que seu backend solicitou para esta tentativa. Veja [Configuração do Backend](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md)                                  |
| `personId`                 | String                 | Sim         | Identificador do usuário                                                                                                                                                                                           |
| `customLocalization`       | String?                | Não         | Nome da tabela de strings para localização personalizada (por exemplo, "stringsBundle")                                                                                                                            |
| `customLocalizationBundle` | Bundle?                | Não         | Bundle que contém a tabela de strings personalizada                                                                                                                                                                |
| `uiCustomization`          | CerttaUiCustomization? | Não         | Identidade visual para a tela de liveness (padrão: `nil`, sem personalização). Veja [Personalização da UI](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/configuration/ui-customization.md) |
| `environment`              | CafEnvironment (enum)  | Não         | `.dev`, `.beta`, `.prod` (padrão: `.prod`)                                                                                                                                                                         |
| `loading`                  | Bool                   | Não         | Mostrar tela de carregamento do SDK (padrão: `verdadeiro`)                                                                                                                                                         |

### Localização personalizada com um bundle de framework

`customLocalization` é o nome da tabela de strings (omita a `.strings` extensão). Quando `Localizable.strings` forem incluídas dentro de um framework (ou outro bundle que não seja o principal), passe tanto o nome da tabela quanto o bundle:

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

Referência de localização: [Localização do iProov](https://github.com/iProov/ios/wiki/Localization)

### Personalização da UI

Para personalizar a tela de liveness — barra de cabeçalho, prompt de orientação, área ao redor do oval do rosto e fonte — passe um `CerttaUiCustomization` por meio do `uiCustomization` parâmetro de `setup`. Disponível a partir de **2.1.0** e totalmente opcional. Veja [Personalização da UI](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/configuration/ui-customization.md).

## Pré-carregar

`prewarm()` realiza a solicitação de sessão com antecedência para que `startSDK` possa abrir a câmera sem esperar pela rede. Chame-o em qualquer momento em que o usuário já esteja ocupado — uma tela de instruções, uma etapa de consentimento, um formulário — e a ida e volta ocorrerá paralelamente ao tempo de leitura dele, em vez de somar a ele.

```swift
sdk.setup(mobileToken: "your_mobile_token", personId: "your_person_id")
sdk.prewarm()                       // por ex., quando a tela de instruções aparecer
// … o usuário lê as instruções …
sdk.startSDK(viewController: self)  // consome a sessão pré-aquecida
```

`prewarm()` retorna imediatamente e não informa nada: ele não tem handler de conclusão e nunca invoca o delegate. É seguro chamá-lo de qualquer thread e chamá-lo mais de uma vez também — enquanto uma solicitação estiver em andamento, ou enquanto uma sessão válida já estiver em cache, ele não faz nada em vez de solicitar uma segunda sessão. É uma operação sem efeito antes de `setup`.

{% hint style="info" %}
**Pré-carregar é sempre opcional e nunca pode quebrar uma captura.** Se nenhuma sessão válida estiver disponível quando `startSDK` for executado — porque o pré-carregamento falhou, nunca foi chamado ou a sessão em cache não é mais utilizável — o SDK faz fallback silencioso para solicitar a sessão no momento, exatamente como fazia antes da 3.0.0.
{% endhint %}

Uma sessão pré-carregada é descartada quando:

| Condição                             | Detalhe                                                                                                                |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Ela tem mais de **90 segundos**      | Inicie a captura dentro dessa janela para aproveitar o pré-carregamento                                                |
| Credenciais ou ambiente alterados    | Uma posterior `setup` com um diferente `mobileToken`, `personId` ou `environment` a invalida                           |
| O app foi enviado para segundo plano | A sessão em cache e as credenciais armazenadas são apagadas                                                            |
| Ela já foi usada                     | Cada sessão pré-carregada é consumida por uma única `startSDK` chamada; chame `prewarm()` novamente para outra captura |

Dois comportamentos a serem observados ao integrar:

* **Não `loading()` / `loaded()` o par é emitido para a solicitação de sessão no caminho pré-carregado**, já que não há nada pelo que esperar. No **3.1.0** nenhum é emitido após a captura também, porque o resultado é entregue imediatamente. Não dependa de `loading()` como sinal de que a captura começou.
* `prewarm()` armazena o token móvel e o ID da pessoa no chaveiro antes de fazer a solicitação, porque a solicitação é autenticada a partir do chaveiro. Eles são removidos se o pré-carregamento falhar ou o app for colocado em segundo plano.

## Iniciar Liveness

`startSDK` apresenta a tela de captura usando a configuração fornecida a `setup`. Ele recebe apenas o view controller apresentador. Chame-o na thread principal.

| Parâmetro        | Tipo             | Obrigatório | Descrição                      |
| ---------------- | ---------------- | ----------- | ------------------------------ |
| `viewController` | UIViewController | Sim         | O view controller apresentador |

Chamar `startSDK` sem um prévio `setup` não apresenta nada — ele retorna `didFinishWithError(type: .invalidOptionsException, description:)` em vez disso. Veja [Tratamento de erros](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/error-handling.md#invalidoptionsexception).

`startSDK` verifica o acesso à câmera antes de qualquer solicitação de rede. Se o usuário ainda não tiver decidido, o prompt do sistema é exibido; se o acesso for negado, o SDK informa `didFinishWithError(type: .cameraPermission, description:)`.

Chamar `startSDK` enquanto uma captura já estiver em execução é ignorada — nada é apresentado e nenhum método do delegate é chamado.

{% hint style="warning" %}
**Mudanças na 2.0.0:** `executeFaceAuth` foi removido. O SDK inicia uma transação assíncrona e retorna apenas `signedResponse`. Recupere o resultado final de liveness no seu backend.
{% endhint %}

## Exemplo completo

```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
        )
        // Opcional: sobreponha a solicitação de sessão com o que quer que o usuário faça em seguida
        sdk.prewarm()

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

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

extension MainViewController: CafFaceLivenessLiteDelegate {
    func didFinishWithSuccess(livenessResult: CafFaceLivenessLiteResult) {
        // JWT opaco do fluxo assíncrono — resolva o resultado final no seu backend
        print("Sucesso: \(livenessResult.signedResponse ?? "-")")
    }

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

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

    func cancelled() { print("Cancelado") }
    func loading() { print("Carregando") }
    func loaded() { print("Carregado") }
}
```

## Eventos

O `CafFaceLivenessLiteDelegate` o protocolo lida com os principais eventos durante o processo de liveness. Uma execução sempre termina com exatamente um de `didFinishWithSuccess`, `didFinishWithFailure`, `didFinishWithError` ou `cancelled()`.

| Evento                                                                                      | Descrição                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `didFinishWithSuccess(livenessResult: CafFaceLivenessLiteResult)`                           | Chamado assim que a captura é concluída; inclui `signedResponse` JWT                                                                                                                                                                 |
| `didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?)` | Chamado quando a captura é concluída sem aprovação (iluminação, alinhamento etc.); sempre inclui a sessão `signedResponse`. Veja [Falhas mobile](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile.md) |
| `didFinishWithError(type: CafErrorType, description: String)`                               | Chamado em caso de erro de execução (permissão, rede, token etc.). Veja [Tratamento de erros](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/error-handling.md) para cada tipo e como tratá-lo          |
| `cancelled()`                                                                               | Usuário cancelou o fluxo                                                                                                                                                                                                             |
| `loading()`                                                                                 | O SDK começou a aguardar a solicitação de sessão                                                                                                                                                                                     |
| `loaded()`                                                                                  | O SDK parou de aguardar: emitido quando a solicitação de sessão é concluída e novamente quando o fluxo termina, logo após o callback final                                                                                           |

Para os campos e tipos retornados por cada callback, veja [Referência de resultados](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/result-reference.md).

`loading()` e `loaded()` são emitidos independentemente de o `loading` opção de `setup` estar habilitada. Essa opção apenas exibe ou oculta a tela de carregamento integrada do SDK.

De **3.0.0**quando uma sessão pré-carregada é consumida, não há solicitação de sessão pela qual esperar, então nenhum `loading()` / `loaded()` par é emitido para essa etapa.

De **3.1.0**nenhum `loading()` / `loaded()` par é emitido após a captura também: o resultado é entregue no momento em que a captura termina, e a tentativa é registrada. No caminho pré-carregado, isso significa que o delegate talvez nunca receba `loading()` de forma alguma — não dependa disso como sinal de que a captura começou.

{% hint style="warning" %}
Nunca decida o resultado de liveness no dispositivo. Seu backend valida o `signedResponse` e recupera o resultado final.
{% endhint %}

## Alterando o usuário ou as credenciais

Você pode chamar `setup` novamente para alterar qualquer valor — por exemplo, para alternar `personId` entre usuários. Fazer isso descarta uma sessão pré-carregada anterior sempre que as credenciais ou o ambiente forem diferentes. Chame `prewarm()` novamente após reconfigurar.

## getVersion

```swift
let version = CafFaceLivenessLiteSDK.getVersion() // por exemplo, "7.8.0"
```

Disponível a partir de **7.8.0**. Método estático que retorna a versão do SDK como uma `String`. Ele não precisa de uma instância nem de `setup`, o que o torna útil para logs e chamados de suporte.

## Próximo passo

Encaminhe o `signedResponse` para o seu backend, que o valida e obtém o resultado: [Configuração do Backend](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/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/sdk-lite-english-pt-br/configuracao/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.
