> 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/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/start-sdk.md).

# Iniciar verificação de liveness

Links rápidos: [Visão geral](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite.md) | [Construindo o SDK](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/builder.md) | [Iniciar verificação de vivacidade](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/start-sdk.md) | [Personalização da UI](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/ui-customization.md) | [Instalação](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/installation.md) | [Versão atual](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/current-version.md) | [Requisitos](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/requirements.md) | [Código-fonte](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/source-code.md) | [Referência do resultado](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/result-reference.md) | [Notas de versão](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/release-notes.md) | [Perguntas frequentes](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/faq_caf_face_liveness_sdk.md)

De **3.0.0** o fluxo tem três etapas: configure uma vez com `setup`, opcionalmente `pré-aquecer` a sessão e depois `startSDK` para exibir a tela de captura.

{% hint style="warning" %}
**Alterações na 3.0.0:** a configuração foi movida de `startSDK` para `setup`. O antigo `startSDK(viewController:mobileToken:personId:…)` sobrecarga foi removida — as chamadas existentes não irão compilar. Veja o [guia de migração](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/release-notes.md).
{% endhint %}

## Configurando com setup

Chame `setup` antes de iniciar. Ele apenas armazena sua configuração — não faz nenhuma requisição de rede e não exibe nada.

| Parâmetro                                 | Obrigatório | Descrição                                                                                 |
| ----------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `mobileToken: String`                     | Sim         | Token de uso associado à sua conta CAF                                                    |
| `personId: String`                        | Sim         | Identificador do usuário                                                                  |
| `customLocalization: String?`             | Não         | Nome da tabela de strings para localização personalizada do iProov (ex.: "stringsBundle") |
| `customLocalizationBundle: Bundle?`       | Não         | Bundle contendo a tabela de strings personalizada (iProov `options.stringsBundle`)        |
| `uiCustomization: CerttaUiCustomization?` | Não         | Identidade visual da tela de vivacidade (padrão: `nil`, sem personalização)               |
| `environment: CafEnvironment`             | Não         | `.dev`, `.beta`, `.prod` (padrão: `.prod`)                                                |
| `loading: Bool`                           | Não         | Exibir tela de carregamento do SDK (padrão: `true`)                                       |

Você pode chamar `setup` novamente para alterar qualquer valor — por exemplo, para alternar `personId` entre usuários. Ao fazer isso, qualquer sessão pré-aquecida anteriormente é descartada sempre que as credenciais ou o ambiente forem diferentes.

## Pré-aquecimento da sessão (opcional)

`prewarm()` faz a requisição da 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 o tempo de ida e volta se sobreponha ao tempo de leitura, em vez de aumentá-lo.

```swift
sdk.setup(mobileToken: "your_mobile_token", personId: "your_person_id")
sdk.prewarm()                       // por exemplo, 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: não tem callback de conclusão e nunca invoca o delegate. É seguro chamá-lo de qualquer thread e seguro chamá-lo mais de uma vez — enquanto uma requisição estiver em andamento, ou enquanto já houver uma sessão válida em cache, ele não faz nada em vez de solicitar uma segunda sessão.

**O pré-aquecimento é sempre opcional e nunca pode comprometer uma captura.** Se nenhuma sessão válida estiver disponível quando `startSDK` for executado — porque o pré-aquecimento falhou, nunca foi chamado ou a sessão em cache não é mais utilizável — o SDK faz um fallback silencioso para solicitar a sessão inline, exatamente como fazia antes da 3.0.0.

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

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

Dois comportamentos que vale notar ao integrar:

* **Não `loading()` / `loaded()` um par é emitido para a requisição da sessão no caminho pré-aquecido**, pois não há nada para aguardar. A partir de **3.1.0** nenhum é emitido após a captura também, porque o resultado é entregue imediatamente. Não confie em `loading()` como um sinal de que a captura começou.
* `prewarm()` armazena o token móvel e o ID da pessoa no chaveiro antes de emitir a requisição, porque a requisição é autenticada a partir do chaveiro. Eles são removidos se o pré-aquecimento falhar ou se o app for enviado para o plano de fundo.

## Chamar startSDK

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

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

Chamando `startSDK` sem uma configuração prévia `setup` não exibe nada — ele informa `didFinishWithError(type: .invalidOptionsException, description:)` em vez disso. Veja [Referência do resultado](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/result-reference.md).

`startSDK` verifica o acesso à câmera antes de qualquer requisiçã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:)`.

Chamando `startSDK` enquanto uma captura já estiver em andamento é ignorado — nada é exibido e nenhum método do delegate é chamado.

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

### Exemplo

```swift
import CafFaceLivenessLite

class ViewController: UIViewController {
    private let sdk = CafFaceLivenessLiteSDK()

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

        sdk.setup(
            mobileToken: "your_mobile_token",
            personId: "your_person_id",
            customLocalization: nil,
            customLocalizationBundle: nil,
            environment: .prod,
            loading: true
        )
        sdk.prewarm()
    }

    func startLiteLiveness() {
        sdk.startSDK(viewController: self)
    }
}
```

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

Quando os `Localizable.strings` forem empacotados dentro de um framework (ou de outro bundle que não seja o principal), informe tanto o nome da tabela quanto o 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)
```

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 vivacidade — barra de cabeçalho, prompt de orientação, área ao redor do oval do rosto e fonte — passe uma `CerttaUiCustomization` por meio do `uiCustomization` parâmetro de `setup`. Disponível em **2.1.0** e totalmente opcional. Veja [Personalização da UI](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/ui-customization.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/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/caffacelivenesslite/start-sdk.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.
