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

# Face Liveness

{% hint style="warning" %}
Este guia abrange a versão 7.14.0 e superior. Para versões anteriores à 7.14.0, consulte a [documentação legada](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% endhint %}

## Pré-requisitos

Antes de continuar, certifique-se de que o Certta SDK esteja instalado corretamente. Se você ainda não fez isso, consulte nosso Guia de Instalação.

{% content-ref url="/pages/c4edac6f06cfb1bc5036e5a528cfe09e4dbd5ff6" %}
[Guia de Instalação](/caf-sdk/caf-sdk-pt-br/android/installation-guide.md)
{% endcontent-ref %}

## Iniciando o Liveness

Para iniciar o fluxo de Liveness, chame `CerttaLiveness.instance.open()` e passe um `LivenessConfiguration` objeto.

{% hint style="info" %}
Este método aceita um callback para tratar os resultados e eventos acionados durante o fluxo de Liveness.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}
{% code expandable="true" %}

```kotlin
val livenessConfig = LivenessConfiguration(
    maxRetryAttempts = 3,
    faceAuthEnabled = false,
    showLoading = true,
    useFaceLivenessUi = true
)
CerttaLiveness.instance.open(livenessConfig) { event ->
    when (event) {
        is LivenessEvent.Completed -> {
            when (val result = event.result) {
                is LivenessResult.Success -> {
                    // Tratar sucesso
                }
                is LivenessResult.Failed -> {
                    // Tratar falha
                }
            }
        }
        is LivenessEvent.Error -> {
            // Tratar erro
        }
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}

```java
LivenessConfiguration livenessConfiguration = new LivenessConfiguration(
    3,      // tentativas máximas de nova tentativa
    false,  // autenticação facial desativada
    true,   // mostrar carregamento
    true    // usar UI de Liveness facial
);
CerttaLiveness.getInstance().open(livenessConfiguration, new CerttaLivenessListener() {
    @Override
    public void onEvent(@NotNull LivenessEvent event) {
        if (event instanceof LivenessEvent.Completed) {
            LivenessResult result = ((LivenessEvent.Completed) event).getResult();    
            if (result instanceof LivenessResult.Success) {
                // Tratar sucesso
            } else if (result instanceof LivenessResult.Failed) {
                // Tratar falha
            }    
        } else if (event instanceof LivenessEvent.Error) {
            // Tratar erro    
        }
    }
});
```

{% endtab %}
{% endtabs %}

### `LivenessConfiguration` Parâmetros

| Parâmetro           | Padrão  | Descrição                                                                   |
| ------------------- | ------- | --------------------------------------------------------------------------- |
| `maxRetryAttempts`  | `3`     | Máximo de novas tentativas após uma tentativa de captura com falha.         |
| `faceAuthEnabled`   | `false` | Quando **ativado**, o SDK executa **autenticação facial.**                  |
| `showLoading`       | `true`  | Mostra indicadores de carregamento durante o processamento quando **true**. |
| `useFaceLivenessUi` | `false` | Se **ativado**, o SDK usa a UI Certta integrada.                            |

## Entendendo eventos e resultados de Liveness

Para lidar com o resultado do fluxo de Liveness, passe um callback para o `CerttaLiveness.instance.open()` método para ouvir eventos de **sucesso**, **falha**, ou **erro** eventos.

{% 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 %}

### **`LivenessEvent.Completed(result: LivenessResult)`**

Este evento indica que o fluxo da UI foi concluído. Ele contém um `LivenessResult` que você deve avaliar:

1. **`LivenessResult.Success(response: String)`:** A captura e o pipeline de Liveness foram concluídos com sucesso. **`response`** é um JWT contendo os dados de resultado obtidos durante a execução de Liveness. Esses dados podem incluir informações relevantes para o processo, como imagens capturadas ou resultados de validação.
2. **`LivenessResult.Failed(failure: LivenessFailure)`:** O Liveness foi executado, mas o resultado é uma falha de negócio. Veja **`LivenessFailure`** abaixo.

### **`LivenessFailure`**

Indica que a verificação de liveness terminou com falha. Há duas variantes:

1. **`LivenessFailure.imageCaptureFailure(cause: String)`:** Problemas durante a captura, como problemas no ambiente, timeout, nenhum rosto detectado ou falha específica do provedor. O `causa` destina-se a diagnósticos ou mensagens de UX.
2. **`LivenessFailure.faceRecognitionFailure(result: String, cause: String)`:** A captura foi bem-sucedida, mas **reconhecimento facial / backend** não aceitou o resultado. `causa` explica a rejeição, e `result` é a carga útil assinada.

{% hint style="info" %}
Para entender e lidar com o `causa` da falha, consulte Liveness Error
{% endhint %}

### **`LivenessEvent.Error(error: CerttaError)`**

É acionado quando um bloqueio técnico impede o SDK de iniciar ou concluir o processo, como permissões de câmera negadas, ausência de conexão com a internet ou falhas na inicialização do hardware.

| Evento                  | Causa típica                                                                                                                              |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `erro de inicialização` | **`configurar`** não chamado, token ou ID de usuário vazio, ou inválido **`maxRetryAttempts`**.                                           |
| `erro de permissão`     | Permissão da câmera (ou relacionada) negada.                                                                                              |
| `erro de rede`          | Problemas de conectividade ou do lado do servidor se manifestam como erros da classe de rede.                                             |
| `erro de segurança`     | As verificações de segurança falharam.                                                                                                    |
| `erro desconhecido`     | Outras falhas não mapeadas para um caso específico.                                                                                       |
| `cancelado`             | Ocorre quando o usuário abandona o fluxo antes da conclusão, como ao pressionar o botão voltar ou enviar o aplicativo para segundo plano. |


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/getting-started-with-the-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.