> 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/react-native/face-liveness.md).

# Face Liveness

Instale e inicie o Face Liveness para React Native. Aprenda sobre os pré-requisitos, opções de CerttaLivenessConfiguration, eventos do hook, resultados de sucesso e falha e tratamento de erros.

{% hint style="warning" %}
Este guia aborda **@caf.io/react-native-sdk 5.4.0** e acima (Certta DevX). Para o sequencial anterior `useCafSdk` fluxo, veja o [documentação legada](https://docs.caf.io/caf-sdk/react-native/getting-started-with-the-sdk).
{% endhint %}

## Pré-requisitos

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

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

Ativar `faceLiveness` (e `faceLivenessUI` se você quiser a interface de usuário integrada) em `caf-modules-config.json`. Você deve incluir pelo menos um provedor de liveness.

## Iniciando o Liveness

Use o `useCafFaceLiveness` hook e chame `open()` com um `CerttaLivenessConfiguration` objeto. O hook se inscreve automaticamente nos eventos nativos — leia os resultados do `evento` estado.

{% hint style="info" %}
Defina `useFaceLivenessUi` para `true` para usar a interface de usuário integrada da Certta. Quando `false`, o SDK executa o módulo Face Liveness sem interface.
{% endhint %}

```typescript
import { useEffect } from 'react';
import { useCafFaceLiveness } from '@caf.io/react-native-sdk';

function LivenessScreen() {
  const { open, event } = useCafFaceLiveness();

  useEffect(() => {
    if (event.success) {
      // Lidar com sucesso — event.success.response é um JWT
    } else if (event.failed) {
      // Lidar com falha de negócio — veja Tratamento de Falhas
    } else if (event.error) {
      // Lidar com erro técnico
    }
  }, [event]);

  const startLiveness = async () => {
    try {
      await open({
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true,
      });
    } catch {
      // Trate BRIDGE_EXCEPTION
    }
  };

  // ...
}
```

`open()` rejeita com `CerttaPlatformException` e código `BRIDGE_EXCEPTION` quando o mapeador nativo rejeita a configuração.

### `CerttaLivenessConfiguration` parâmetros

| Parâmetro           | Padrão  | Descrição                                                                           |
| ------------------- | ------- | ----------------------------------------------------------------------------------- |
| `maxRetryAttempts`  | `3`     | Máximo de tentativas de repetição após uma tentativa de captura com falha.          |
| `faceAuthEnabled`   | `false` | Quando **ativado**, o SDK executa **autenticação facial**.                          |
| `showLoading`       | `true`  | Exibe indicadores de carregamento durante o processamento quando **true**.          |
| `useFaceLivenessUi` | `false` | Se **ativado**, o SDK usa a interface de usuário integrada do Certta Face Liveness. |
| `payFaceDebugMode`  | `false` | Ativa o modo de depuração para o provedor PayFace. **apenas iOS**.                  |

## Entendendo eventos e resultados do Liveness

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

O hook `evento` objeto tem no máximo um campo preenchido:

### `success` (`CerttaSuccess`)

O pipeline de captura e liveness foi bem-sucedido. **`response`** é um JWT com os dados de resultado da execução do Liveness.

### `falha` (`CerttaLivenessFailure`)

O Liveness foi executado, mas o resultado é uma falha de negócio.

| Campo         | Descrição                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `type`        | `CerttaLivenessFailureType.ImageCaptureFailure` ou `CerttaLivenessFailureType.FaceRecognitionFailure`.                   |
| `causa`       | Identificador para diagnósticos ou mensagens de UX (por exemplo `TOO_DARK`). Convertido para maiúsculas pelo plugin RN.  |
| `description` | Descrição opcional legível por humanos do SDK nativo.                                                                    |
| `response`    | Payload assinado. Presente para `FaceRecognitionFailure` quando a captura foi bem-sucedida, mas o reconhecimento falhou. |

{% hint style="info" %}
Para entender e lidar com a `causa` da falha, veja [Tratamento de Falhas](/caf-sdk/caf-sdk-pt-br/react-native/face-liveness/handling-failures.md).
{% endhint %}

### `error` (`CerttaError`)

Acionado quando um bloqueio técnico impede o SDK de iniciar ou concluir o processo.

| Campo   | Descrição                                             |
| ------- | ----------------------------------------------------- |
| `type`  | Identificador do erro mapeado a partir do SDK nativo. |
| `causa` | Contexto adicional da falha, quando presente.         |

| Evento                  | Causa típica                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Erro de inicialização` | **`configurar`** não chamado, token vazio 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 aparecem como erros 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 app 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 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/react-native/face-liveness.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.