> 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/getting-started-with-the-sdk-1.md).

# Face Liveness

Instale e configure o Face Liveness para iOS com os CafSDKs. Saiba mais sobre requisitos, configuração de sessão, fluxo de face liveness, configuração da UI, delegates, temas e suporte.

{% hint style="warning" %}

## Este guia abrange a versão 7.0.0 e superiores. Para versões anteriores à 7.0.0, consulte a [documentação legada](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-5.md).

{% endhint %}

### Visão geral

Este guia cobre a instalação do SDK, a inicialização da sessão e como acionar o fluxo de Face Liveness.

### Pré-requisitos

Antes de prosseguir, verifique se o CAF SDK está instalado corretamente. Se você ainda não fez isso, consulte nosso [Guia de Instalação](https://www.google.com/search?q=%23).

### Iniciando o Face Liveness

Para iniciar o fluxo de liveness, use a instância singleton e forneça os parâmetros de configuração necessários. Use o manipulador de conclusão para gerenciar os eventos e resultados da sessão.

```swift
CerttaLiveness.shared.open(
    from: self, // Este é o view controller e o delegate
    configuration: LivenessConfiguration(
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true 
    )
) 
```

***

#### `LivenessConfiguration` Parâmetros

Todos os parâmetros têm valores padrão; substitua apenas o que você precisar.

<table><thead><tr><th>Parâmetro</th><th width="279">Padrão</th><th>Descrição</th></tr></thead><tbody><tr><td><code>maxRetryAttempts</code></td><td><code>3</code></td><td>Número máximo de tentativas após uma tentativa de captura com falha.</td></tr><tr><td><code>faceAuthEnabled</code></td><td><code>false</code></td><td>Quando <strong>habilitado</strong>, o SDK executa <strong>autenticação facial.</strong></td></tr><tr><td><code>showLoading</code></td><td><code>true</code></td><td>Mostra indicadores de carregamento durante o processamento quando <strong>true</strong>.</td></tr><tr><td><code>useFaceLivenessUi</code></td><td><code>false</code></td><td>Se <strong>habilitado</strong>, o SDK usa a interface integrada da Certta.</td></tr></tbody></table>

### Entendendo eventos e resultados do Liveness

O `CerttaLiveness.instance.open()` atribui seu controlador a um delegate para o qual você precisa declarar estes métodos:

{% hint style="warning" %}
Garanta que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos `estáVivo` e `éCorrespondente` campos. Não realize essas validações no lado do cliente.
{% endhint %}

```swift
extension CerttaViewController: CerttaLivenessDelegate, CerttaDelegate {
    func didFinish(signedResponse: String) {
        let out = formView.outputView
        out.text += "✅ Captura concluída com sucesso\n"    
    }

    func didFail(_ failure: LivenessFailure) {
    let out = formView.outputView
    switch failure {
    case .faceRecognitionFailure(let result, let cause, let description):
        out.text += "❌ Falha no liveness (face): cause=\(cause), description=\(description), result=\(result)\n\n"
    case .imageCaptureFailure(let message):
        out.text += "❌ Falha no liveness (captura): \(message)\n\n"
        }
    }
  
    func didFinishWith(_ error: CerttaError) {
        let out = formView.outputView
        switch error {
        case .initializationError(let message): out.text += "❌ Erro: \(message)\n\n"
        case .permissionError(let message): out.text += "❌ Erro: permissão - \(message)\n\n"
        case .securityError(let message): out.text += "❌ Erro: segurança - \(message)\n\n"
        case .unknownError(let message): out.text += "❌ Erro: \(message)\n\n"
        case .networkError(let message): out.text += "❌ Erro: rede - \(message)\n\n"
        }
    }
    func didLog(level: String, message: String) {
        print("nível: \(level), mensagem: \(message)")
    }
}
```

#### `didFinish(signedResponse: String)`

A string é o **resultado assinado** do módulo. A documentação de integração do seu backend ou da CAF define como **validar**, **decodificar**, e **armazenar** isso. Não **faça** log do token completo em builds de produção.

#### `didFail(_ failure: LivenessFailure)`

Existem dois tipos de **`LivenessFailure`**:

| Caso                                                                          | Quando                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.imageCaptureFailure(String)`                                                | Problemas durante **a captura** (ambiente, tempo limite, nenhuma face etc.). A string é a mensagem de erro, destinada a **diagnósticos** ou mensagens de UX.                                                                                                                                                                                                                                                    |
| `.faceRecognitionFailure(result: String, cause: String, description: String)` | A captura foi bem-sucedida, mas **o reconhecimento facial / backend** não aceitou o resultado. **`causa`** é um código estável em snake\_case para a rejeição (veja [estável `causa` valores](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-1/handling-failures.md#stable-cause-values)), **`descrição`** é a mensagem legível e localizada para humanos, e **`resultado`** é o **payload assinado**. |

{% hint style="info" %}
`descrição` está disponível em **7.8.0**. Antes da 7.8.0, `faceRecognitionFailure` tinha apenas `resultado` e `causa`, e `causa` que continha a mensagem. Veja o [Changelog](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-4.md).
{% endhint %}

#### `didFinishWith(_ error: CerttaError)`

Disparado quando um bloqueador técnico impede o SDK de iniciar ou concluir o processo, como permissões de câmera negadas, sem conexão com a internet ou falhas na inicialização do hardware.

| Evento                    | Causa típica                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| **`initializationError`** | **`configure`** não foi chamado, token ou ID de usuário vazio, ou inválido **`maxRetryAttempts`**. |
| **`permissionError`**     | Permissão da câmera (ou relacionada) negada.                                                       |
| **`networkError`**        | Problemas de conectividade ou do lado do servidor aparecem como erros da classe de rede.           |
| **`securityError`**       | As verificações de segurança falharam.                                                             |
| **`unknownError`**        | Outras falhas não mapeadas para um caso específico.                                                |

**`CerttaError`** conforma-se a **`LocalizedError`**. Use **`localizedDescription`** (ou **`message`**) nos alertas.

#### `didLog(level: String, message: String)`

Usado para **eventos de** e **informativos** , por exemplo:

* Estados Loading / Loaded: mensagens que você pode mapear para a UI ou analytics.

***

### Permissões e experiência do usuário

* Solicite acesso à câmera **antes** de abrir o Face Liveness se o fluxo do seu app permitir; caso contrário, o SDK pode retornar **`permissionError`**.
* Garanta boa iluminação e um texto que explique **por que** o usuário deve concluir uma breve captura ao vivo.

***

## Tematização de cores

* **Certta**: use a sessão **`colorConfiguration`** e **`useFaceLivenessUi`** em **`LivenessConfiguration`** para personalizar a UI do Face Liveness.
* **Modo escuro / claro**: construa **`CafColorConfiguration`** usando **`UITraitCollection.current.userInterfaceStyle`** se você precisar de paletas diferentes

```swift
Certta.shared.setColorConfiguration(CafColorConfiguration(
        primaryColor: "#FFFFFF",
        secondaryColor: "#222222",
        contentColor: "#FFFFFF",
        backgroundColor: "#000000",
        mediumColor: "#555555",
        dialogBackgroundColor: "#1C1C1E",
        dialogBorderColor: "#E5E5E7"
      )
)
```

| Propriedade             | Tipo     | Descrição                                             | Formato                             |
| ----------------------- | -------- | ----------------------------------------------------- | ----------------------------------- |
| `primaryColor`          | `String` | Botões primários, destaques.                          | Código hexadecimal (ex.: `#FF0000`) |
| `secondaryColor`        | `String` | Elementos secundários, bordas.                        | Código hexadecimal                  |
| `contentColor`          | `String` | Texto e ícones.                                       | Código hexadecimal                  |
| `Cor de fundo da tela.` | `String` | Cor de fundo da tela.                                 | Código hexadecimal                  |
| `mediumColor`           | `String` | Elementos neutros (por exemplo, barras de progresso). | Código hexadecimal                  |
| `dialogBackgroundColor` | `String` | Cor de fundo de diálogos e pop-ups.                   | Código hexadecimal                  |
| `dialogBorderColor`     | `String` | Cor da borda de diálogos e pop-ups.                   | Código hexadecimal                  |

***

### Notas de versão

Consulte [**Changelog**](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-4.md) para versões, mudanças que quebram compatibilidade e Xcode / iOS mínimo.

***

## Suporte técnico e dicas de uso

Para mais detalhes e cenários avançados de uso, consulte os seguintes recursos:

* **Repositório no GitHub:** acesse o código-fonte, o rastreamento de issues e as notas de versão no [repositório GitHub do CafSDK](https://github.com/combateafraude/caf-ios-sdk).
* **Perguntas frequentes e solução de problemas**: consulte nossa seção de FAQ para problemas comuns e dicas de solução de problemas.
* **Suporte**: para assistência adicional, entre em contato com nossa equipe de suporte ou participe do fórum da nossa comunidade de desenvolvedores.

Atualizamos continuamente a documentação à medida que novos recursos e melhorias são lançados. Fique por dentro das próximas atualizações!


---

# 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/getting-started-with-the-sdk-1.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.