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

# Primeiros passos com o SDK

## Sobre o CafSDK

Esta documentação técnica abrange a **implementação do CafSDK para React Native**, detalhando a configuração, inicialização, execução dos fluxos de captura e personalizações avançadas.

O CafSDK é um SDK unificado que integra vários módulos para verificação de identidade: **Face Liveness (FL)** e **Document Detector (DD)**, executados sequencialmente com uma interface de configuração unificada.

### O que é Face Liveness

Face Liveness é o módulo que valida a autenticidade de um rosto capturado por um aplicativo de fotos, garantindo que a imagem corresponda a uma pessoa real e não a uma tentativa de falsificação.

**Características técnicas:**

* Configuração de URL para autenticação (`authBaseUrl`) e verificação de vivacidade (`livenessBaseUrl`)
* Suporte à configuração de proxy reverso com pinning de certificado
* Flags para habilitar captura de tela e modo de depuração
* Tentativas de repetição configuráveis e execução da autenticação facial
* Suporte a múltiplos provedores de autenticação

### O que é Document Detector

Document Detector é o módulo que permite a captura e o processamento de documentos (por exemplo, RG, cartão da previdência social, passaporte etc.).

**Características técnicas:**

* Configuração de um fluxo passo a passo definido por `CafDocumentDetectorFlow` para captura de documentos
* Suporte a múltiplos tipos de documentos (RG, CNH, passaporte etc.)
* Parâmetros operacionais, como timeout, flags de captura manual e outras configurações
* Possibilidade de usar a câmera para validações de enquadramento ou upload de arquivo de documento
* Opções avançadas de personalização da interface, mensagens e comportamento

***

## Instalação

### Requisitos

Para usar os módulos do CafSDK no React Native, certifique-se de que seu projeto atenda aos requisitos mínimos:

#### React Native

| Requisito                  | Versão |
| -------------------------- | ------ |
| **Versão do React Native** | 0.73.x |
| **Node.js**                | 18     |

#### Android

| Requisito                                               | Versão |
| ------------------------------------------------------- | ------ |
| **Android SDK API - versão mínima (minSdk)**            | 26     |
| **Android SDK API - versão de compilação (compileSdk)** | 36     |
| **Kotlin**                                              | 1.9.10 |
| **Gradle**                                              | 8.4    |
| **Android Gradle Plugin (AGP)**                         | 8.3.2  |

#### iOS

| Requisito                        | Versão |
| -------------------------------- | ------ |
| **Target de implantação do iOS** | 15.0   |
| **Xcode**                        | 26.0   |
| **Swift**                        | 5.10   |
|                                  |        |

### Passo 1: Instale o SDK

Instale o pacote principal do SDK:

```sh
npm install @caf.io/react-native-sdk
```

### Passo 2: Configure a seleção de módulos

{% tabs %}
{% tab title="Expo" %}
Ao usar o Expo, você não precisa criar manualmente o `caf-modules-config.json` arquivo, ele é gerado automaticamente a partir do `app.json`. 

Para configurar o SDK, adicione o seguinte plugin ao seu `app.json` arquivo:

{% code title="app.json" %}

```json
{
  "plugins": [
    // ... seus plugins
    [
      "@caf.io/react-native-sdk",
      {
        // configuração dos módulos do SDK
        "documentDetector": true,
        "faceLiveness": true,
        "documentDetectorUI": true,
        "faceLivenessUI": true,
        "livenessProviders": ["iproov-lite", "payface"],
        "fingerprint": true
      }      
    ]
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="CLI da comunidade" %}
Para configurar o SDK, crie um `caf-modules-config.json` arquivo no diretório raiz do seu app para controlar quais módulos nativos estão incluídos.

{% code title="caf-modules-config.json" %}

```json
{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": ["iproov-lite", "payface"],
  "fingerprint": true
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Se você omitir a configuração dos módulos do SDK, todos os módulos serão habilitados por padrão, e **`iproov-lite`** será definido como o provedor padrão de Face Liveness.
{% endhint %}

Defina cada flag de módulo como `true` para incluí-lo, ou `false` para excluí-lo.

`livenessProviders` aceita um array de strings.

**iProov e Protobuf**

* **`iproov-lite`**: use quando seu app tiver como alvo **Protobuf JavaLite**— a escolha usual para uma pegada binária menor no Android.
* **`iproov-full`**: use quando você precisar de **Protobuf Java** (completo) junto com o iProov.

{% hint style="warning" %}
Se você incluir o provedor **PayFace** , você também deve usar **iProov Lite** (`iproov-lite`). O PayFace é compilado com base em Protobuf JavaLite; misturá-lo com **`iproov-full`** causa conflitos de dependência do Protobuf no momento da compilação.
{% endhint %}

**Fingerprint**

O módulo Fingerprint é opcional e é configurado em `caf-modules-config.json` por meio da `fingerprint` propriedade (boolean). O valor padrão é `false`, então você não precisa adicionar a propriedade, a menos que queira usá-la. Para habilitar o módulo, defina explicitamente `"fingerprint": true`.

**Requer um módulo Face Liveness.** Fingerprint é coletado como parte do fluxo de vivacidade, então só é incluído quando `faceLiveness` ou `faceLivenessUI` também está habilitado. Definir `"fingerprint": true` sem um módulo de vivacidade habilitado não tem efeito.

**Importante:** Entre em contato com o Suporte da CAF para solicitar a ativação. Se isso não estiver habilitado do nosso lado, o SDK não acionará a biblioteca de fingerprint e nenhum dado será enviado, mesmo que a propriedade esteja definida como `true` localmente.

### Passo 3: Configuração do iOS

Navegue até o `ios/` diretório do seu projeto React Native e execute:

```sh
pod install
```

* Este passo é obrigatório para que o iOS vincule corretamente os módulos nativos e suas dependências necessárias.
* Execute novamente `pod install` sempre que dependências nativas forem adicionadas ou atualizadas.

***

## Permissões

### Android

Para que os módulos funcionem corretamente, você deve declarar as seguintes permissões no seu **AndroidManifest.xml**:

**Para Face Liveness**

| Permissão                     | Descrição                                                                                   | Necessidade |
| ----------------------------- | ------------------------------------------------------------------------------------------- | ----------- |
| `android.permission.CAMERA`   | Permite acesso à câmera para capturar imagens e realizar a verificação facial (vivacidade). | Obrigatória |
| `android.permission.INTERNET` | Permite comunicação com serviços de autenticação e verificação (HTTPS/WSS).                 | Obrigatória |

**Para Document Detector**

| Permissão                                  | Descrição                                                                                       | Necessidade          |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------------------- |
| `android.permission.CAMERA`                | Permite acesso à câmera para capturar imagens do documento.                                     | Somente para captura |
| `android.permission.INTERNET`              | Permite que as imagens capturadas sejam enviadas aos servidores para processamento e validação. | Obrigatória          |
| `android.permission.READ_EXTERNAL_STORAGE` | Permite acesso a arquivos e imagens armazenados para processamento, se necessário.              | Somente para upload  |

### iOS

Para que os módulos do SDK funcionem corretamente, você deve declarar as seguintes permissões no seu **Info.plist**:

**Para Face Liveness:**

| Permissão                  | Descrição                                                                                   | Necessidade |
| -------------------------- | ------------------------------------------------------------------------------------------- | ----------- |
| `NSCameraUsageDescription` | Permite acesso à câmera para capturar imagens e realizar a verificação facial (vivacidade). | Obrigatória |
| `Acesso à rede`            | Permite comunicação com serviços de autenticação e verificação (HTTPS/WSS).                 | Obrigatória |

**Para Document Detector:**

| Permissão                        | Descrição                                                                                       | Necessidade          |
| -------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------- |
| `NSCameraUsageDescription`       | Permite acesso à câmera para capturar imagens do documento.                                     | Somente para captura |
| `Acesso à rede`                  | Permite que as imagens capturadas sejam enviadas aos servidores para processamento e validação. | Obrigatória          |
| `NSPhotoLibraryUsageDescription` | Permite acesso a arquivos e imagens armazenados para processamento, se necessário.              | Somente para upload  |

***

## Implementação Básica

### Exemplo Simples

Aqui está um exemplo básico de implementação:

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

```typescript
import React, { useEffect } from 'react';
import { SafeAreaView, View, Button, Text } from 'react-native';
import {
  useCafSdk,
  CafModuleType,
  CafEnvironment,
  CafDocument,
  useCafFaceLiveness,
  useCafDocumentDetector,
} from '@caf.io/react-native-sdk';

function App(): React.JSX.Element {
  const { initialize, startSDK, response, initialized } = useCafSdk();

  const { applyCafFaceLiveness } = useCafFaceLiveness();

  const { applyCafDocumentDetector } = useCafDocumentDetector();

  const handleInitialize = async () => {
    const result = await initialize({
      configuration: {
        presentationOrder: [
          CafModuleType.FACE_LIVENESS, 
          CafModuleType.DOCUMENT_DETECTOR
        ],
        enableSecurityModule: true,
      },
      mobileToken: 'your-mobile-token',
      environment: CafEnvironment.PROD,
      personId: 'user-person-id',
    },
    async () => {
      const appliedFaceLiveness = await applyCafFaceLiveness({
        maxRetryAttempts: 0,
        executeFaceAuth: false,
      });
      const appliedDocumentDetector = await applyCafDocumentDetector({
        flow: [{ document: CafDocument.CNH_FULL }],
        uploadSettings: {
          enable: true,
        },
        manualCaptureEnabled: false,
        securitySettings: {
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        },
        maxRetryAttempts: 0,
      });
      return appliedFaceLiveness && appliedDocumentDetector;
    });
  };

  const handleStartSDK = () => {
    if (initialized) {
      startSDK();
    }
  };

  useEffect(() => {
    handleInitialize();
  }, []);

  useEffect(() => {
    response.success?.forEach((item: CafSuccessResponse) => {
      if (item.moduleName === 'DOCUMENT_DETECTOR') {
        console.log(item.signedResponse);
      } else if (item.moduleName === 'FACE_LIVENESS') {
        console.log(item.signedResponse);
      }
    });
  }, [response]);

  return (
    <SafeAreaView>
      <View>
        <Button 
          title="Iniciar" 
          onPress={handleStartSDK} 
          disabled={response.loading}
        />
        {response.loading && <Text>Processando...</Text>}
      </View>
    </SafeAreaView>
  );
}

export default App;
```

***

## Configuração

### Idioma

#### Android

O idioma é definido automaticamente de acordo com o idioma configurado no dispositivo, sem necessidade de configurações adicionais.

#### iOS

De acordo com a documentação da Apple, configurar `Localizações` e `CFBundleLocalizations` deve ser feito no Xcode:

[Adicionando suporte a idiomas e regiões](https://developer.apple.com/documentation/xcode/adding-support-for-languages-and-regions)

[CFBundleLocalizations](https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundlelocalizations)

Após essas configurações, o SDK reconhecerá o idioma do dispositivo.

### Configuração Global

O `useCafSdk` hook serve como contêiner central para todas as configurações. A configuração global define a ordem de execução dos módulos e a identidade visual, e é passada para a `initialize()` função.

**Valores retornados:**

* **`initialize`**: Função que inicializa o SDK e aplica as configurações dos módulos. Retorna `Promise<boolean>` indicando se todas as configurações foram aplicadas com sucesso. Aceita a configuração global e uma função de callback que aplica configurações específicas do módulo.
* **`startSDK`**: Função que inicia o fluxo do SDK após a inicialização.
* **`loadSession`**: Função opcional para pré-carregar a sessão do usuário antes de iniciar o fluxo do SDK.
* **`response`**: Objeto que contém os manipuladores de eventos para a execução do SDK (sucesso, erro, carregamento etc.).
* **`initialized`**: Estado booleano que indica se a `initialize` função aplicou com sucesso todas as configurações dos módulos. Esse estado pode ser usado para verificar se as configurações foram aplicadas corretamente antes de chamar `startSDK()`.

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

**Parâmetros essenciais (passados para `initialize()`):**

* **mobileToken**: Token que autentica a solicitação e garante que apenas clientes autorizados iniciem o fluxo
* **personId**: Identificador único do usuário para o qual o fluxo será executado
* **environment**: Define o ambiente de execução (PROD, BETA, DEV)
* **presentationOrder**: Define a sequência em que os módulos serão executados
* **enableSecurityModule**: Habilita ou desabilita o módulo de segurança. Opcional, o padrão é `true`

**Exemplo de código para criar a configuração global:**

<pre class="language-typescript"><code class="lang-typescript"><strong>const { initialize, response, initialized } = useCafSdk();
</strong>const { applyCafFaceLiveness } = useCafFaceLiveness();
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Inicialize o SDK com a configuração global
await initialize(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // ou CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // ou CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      enableSecurityModule: true,       // Opcional, o padrão é true
      waitForAllServices: true,         // Opcional, o padrão é true
      enableTransitionScreens: true,    // Opcional, o padrão é true
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#CCCCCC",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#E5E5E7",
      },
    }
  },
  async () => {
    // Aplicar configuração dos módulos
    // Todas as funções de aplicação agora retornam Promise&#x3C;boolean>
    const appliedFaceLiveness = await applyCafFaceLiveness({
      loading: true,                                                  // Exibe a tela de carregamento durante o processamento
      authBaseUrl: 'https://base-url.com',                            // Opcional, endpoint para autenticação
      livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para a verificação de vivacidade
      certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
      screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
      debugModeEnabled: true,                                         // Habilita logs de depuração
      executeFaceAuth: false,                                         // Habilita a autenticação facial
      maxRetryAttempts: 2,                                            // Número máximo de tentativas
    });
    const appliedDocumentDetector = await applyCafDocumentDetector({
      flow: [
        { document: CafDocument.RG_FRONT },
        { document: CafDocument.RG_BACK }
      ],
      securitySettings: {
        useAdb: true,
        useDebug: true,
        useDevelopmentMode: true,
      },
      manualCaptureEnabled: true,
      manualCaptureTime: 30,
      requestTimeout: 60,
      showPopup: true,
      maxRetryAttempts: 2,
      uploadSettings: {
        enable: true,
        compress: true,
        fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
        maxFileSize: 5, // 5MB
      },
    });

    return appliedFaceLiveness &#x26;&#x26; appliedDocumentDetector;
  },
);
</code></pre>

### **Pré-carregamento de Sessão (Opcional)**

O `loadSession()` método permite pré-carregar a sessão do usuário antes de iniciar o fluxo do SDK. Isso melhora o tempo de abertura do SDK de Face Liveness ao preparar a sessão e a inicialização da câmera com antecedência, resultando em uma inicialização mais rápida do SDK quando `startSDK()` é chamado.

**Quando usar:**

* Quando você quer otimizar a experiência do usuário reduzindo o tempo de carregamento inicial
* Quando você tem a oportunidade de pré-carregar a sessão antes que o usuário realmente precise iniciar o fluxo
* Particularmente útil para a inicialização do módulo Face Liveness

**Exemplo de código:**

```typescript
const { initialize, startSDK, loadSession, response, initialized } = useCafSdk();
const { applyCafFaceLiveness } = useCafFaceLiveness();
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Inicialize o SDK (constrói as configurações)
// initialize() agora retorna Promise<boolean>
await initialize(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // ou CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // ou CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      enableSecurityModule: true,       // Opcional, o padrão é true
      waitForAllServices: true,         // Opcional, o padrão é true
      enableTransitionScreens: true,    // Opcional, o padrão é true
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#CCCCCC",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#E5E5E7",
      },
    }
  },
  async () => {
    // Aplicar configuração dos módulos
    // Todas as funções de aplicação agora retornam Promise<boolean>
    const appliedFaceLiveness = await applyCafFaceLiveness({
      loading: true,                                                  // Exibe a tela de carregamento durante o processamento
      authBaseUrl: 'https://base-url.com',                            // Opcional, endpoint para autenticação
      livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para a verificação de vivacidade
      certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
      screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
      debugModeEnabled: true,                                         // Habilita logs de depuração
      executeFaceAuth: false,                                         // Habilita a autenticação facial
      maxRetryAttempts: 2,                                            // Número máximo de tentativas
    });
    const appliedDocumentDetector = await applyCafDocumentDetector({
      flow: [
        { document: CafDocument.RG_FRONT },
        { document: CafDocument.RG_BACK }
      ],
      securitySettings: {
        useAdb: true,
        useDebug: true,
        useDevelopmentMode: true,
      },
      manualCaptureEnabled: true,
      manualCaptureTime: 30,
      requestTimeout: 60,
      showPopup: true,
      maxRetryAttempts: 2,
      uploadSettings: {
        enable: true,
        compress: true,
        fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
        maxFileSize: 5, // 5MB
      },
    });

    return appliedFaceLiveness && appliedDocumentDetector;
  },
);

// Pré-carregue a sessão (opcional)
loadSession();

// Mais tarde, quando estiver pronto para iniciar o fluxo
startSDK();
```

**Notas importantes:**

* Este método é opcional e pode ser chamado após `initialize()` mas antes de `start()`
* Pré-carregar a sessão ajuda a reduzir o tempo de carregamento inicial quando `start()` for eventualmente chamado
* Isso é particularmente benéfico para a inicialização do módulo Face Liveness

### Configuração Específica do Módulo

#### Configuração do Face Liveness

Usando o `useCafFaceLiveness` hook, você pode configurar o módulo Face Liveness. A configuração é aplicada ao chamar a `applyCafFaceLiveness` função:

```typescript
const { applyCafFaceLiveness } = useCafFaceLiveness();

// Aplique a configuração ao inicializar
await applyCafFaceLiveness({
  loading: true,                                                  // Exibe a tela de carregamento durante o processamento
  authBaseUrl: 'https://base-url.com',                            // Opcional, endpoint para autenticação
  livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para a verificação de vivacidade
  certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
  screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
  debugModeEnabled: true,                                         // Habilita logs de depuração
  executeFaceAuth: false,                                         // Habilita a autenticação facial
  maxRetryAttempts: 2,                                            // Número máximo de tentativas
});
```

#### Configuração do Detector de Documentos

Usando o `useCafDocumentDetector` hook, você pode configurar o módulo Detector de Documentos. A configuração é aplicada ao chamar a `applyCafDocumentDetector` função:

```typescript
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Aplique a configuração ao inicializar
await applyCafDocumentDetector({
  flow: [
    { document: CafDocument.RG_FRONT },
    { document: CafDocument.RG_BACK }
  ],
  securitySettings: {
    useAdb: true,
    useDebug: true,
    useDevelopmentMode: true,
  },
  manualCaptureEnabled: true,
  manualCaptureTime: 30,
  requestTimeout: 60,
  showPopup: true,
  maxRetryAttempts: 2,
  uploadSettings: {
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
    maxFileSize: 5, // 5MB
  },
});
```

***

## Tratamento de Eventos

O `response` objeto do `useCafSdk` hook contém propriedades que tratam eventos gerados durante a execução do fluxo de captura:

* **registro**: Captura mensagens de log com diferentes níveis (DEBUG, USAGE, INFO)
* **carregamento**: Indica o início do processamento do módulo
* **sucesso**: Após a conclusão bem-sucedida, cada módulo dispara um evento contendo um `CafSuccessResponse[]` objeto
* **erro**: Se ocorrer um problema durante a execução, este evento é disparado com a mensagem de erro
* **falha**: Indica uma falha de face liveness, fornecendo detalhes sobre o tipo de falha
* **cancelado**: Indica que o usuário ou o sistema interrompeu o fluxo

### Tipos de Erro (CafErrorType)

| Caso do Enum                       | Condição de Disparo                                |
| ---------------------------------- | -------------------------------------------------- |
| `CAMERA_PERMISSION`                | Acesso à câmera negado                             |
| `UNSUPPORTED_DEVICE`               | Especificações do dispositivo não compatíveis      |
| `NETWORK_EXCEPTION`                | Problemas de conectividade de rede                 |
| `SERVER_EXCEPTION`                 | Falha no processamento no backend                  |
| `TOKEN_EXCEPTION`                  | Token inválido/expirado                            |
| `CAPTURE_ALREADY_ACTIVE_EXCEPTION` | Sessão de captura simultânea                       |
| `UNEXPECTED_ERROR_EXCEPTION`       | Erro crítico irrecuperável                         |
| `USER_TIMEOUT_EXCEPTION`           | Tempo limite de captura excedido                   |
| `IMAGE_NOT_FOUND_EXCEPTION`        | Dados da imagem ausentes                           |
| `TOO_MANY_REQUESTS_EXCEPTION`      | Limite de taxa da API excedido                     |
| `UNKNOWN_EXCEPTION`                | Erro não classificado                              |
| `LIBRARY_EXCEPTION`                | Erro de baixo nível do framework                   |
| `PERMISSION_EXCEPTION`             | Permissões do sistema ausentes                     |
| `INVALID_EXCEPTION`                | Resposta inválida recebida                         |
| `SEQUENCE_INVALID`                 | Sequência de operação inválida                     |
| `LIVENESS_EXCEPTION`               | Erro específico de face liveness                   |
| `FINGERPRINT_EXCEPTION`            | Erro relacionado à impressão digital               |
| `STORAGE_EXCEPTION`                | Erro de acesso ao armazenamento                    |
| `PROXY_EXCEPTION`                  | Erro de configuração do proxy                      |
| `SECURITY_EXCEPTION`               | Erro de validação de segurança                     |
| `BRIDGE_EXCEPTION`                 | Erro de comunicação da ponte nativa ↔ React Native |

### Tipos de Falha (CafFailureType)

|     Caso do Enum    | Condição de Disparo                 | GPA |  LA |
| :-----------------: | ----------------------------------- | :-: | :-: |
|      `UNKNOWN`      | Falha genérica                      |  ✅  |  ❌  |
| `TOO_MUCH_MOVEMENT` | Movimento excessivo da cabeça       |  ✅  |  ❌  |
|     `TOO_BRIGHT`    | Iluminação excessiva                |  ✅  |  ❌  |
|      `TOO_DARK`     | Condições de pouca luz              |  ✅  |  ❌  |
|  `MISALIGNED_FACE`  | Falha no alinhamento do rosto       |  ✅  |  ❌  |
|    `FACE_TOO_FAR`   | Rosto muito distante                |  ✅  |  ❌  |
|   `FACE_TOO_CLOSE`  | Rosto muito próximo                 |  ✅  |  ❌  |
|     `SUNGLASSES`    | Óculos que cobrem os olhos          |  ✅  |  ❌  |
|   `OBSCURED_FACE`   | Obstrução parcial do rosto          |  ✅  |  ✅  |
|    `EYES_CLOSED`    | Olhos fechados durante a captura    |  ✅  |  ✅  |
|   `MULTIPLE_FACES`  | Vários rostos detectados            |  ✅️ |  ✅️ |
|  `BACKGROUND_ISSUE` | Plano de fundo inadequado           |  ❌  |  ✅  |
|    `DEVICE_ISSUE`   | Dispositivo incompatível            |  ❌  |  ✅  |
|      `EYEWEAR`      | Óculos detectados                   |  ❌  |  ✅  |
|   `FACE_NOT_FOUND`  | Falha na detecção do rosto          |  ❌  |  ✅  |
|   `FRAMES_BLURRY`   | Quadros borrados detectados         |  ❌  |  ✅  |
|    `MOTION_ISSUE`   | Erro de movimento do dispositivo    |  ❌  |  ✅  |
|  `LIGHTING_ISSUES`  | Condições de iluminação inadequadas |  ❌  |  ✅  |
|      `REJECTED`     | Transação rejeitada                 |  ❌  |  ✅  |
|    `SYSTEM_ERROR`   | Erro interno do sistema             |  ❌  |  ✅  |
|      `TIMEOUT`      | Tempo limite da sessão              |  ❌  |  ✅  |
|   `USER_NOT_FOUND`  | Falha na busca do usuário           |  ❌  |  ✅  |
|   `DEVICE_RESTART`  | Erro de estado do dispositivo       |  ❌  |  ✅  |
|  `PROCESSING_FAULT` | Erro de processamento               |  ❌  |  ✅  |

***

## Tipos de Documento

### Documentos Suportados (CafDocument)

| Nome         | Descrição                                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `RG_FRONT`   | Frente do documento RG, onde a foto está localizada                                                                           |
| `RG_BACK`    | Verso do documento RG                                                                                                         |
| `RG_FULL`    | Documento RG aberto, exibindo a frente e o verso juntos                                                                       |
| `CNH_FRONT`  | Frente do documento CNH, onde a foto está localizada                                                                          |
| `CNH_BACK`   | Verso do documento CNH                                                                                                        |
| `CNH_FULL`   | Documento CNH aberto, exibindo a frente e o verso juntos                                                                      |
| `CRLV`       | Documento CRLV                                                                                                                |
| `RNE_FRONT`  | Frente do documento RNE ou RNM                                                                                                |
| `RNE_BACK`   | Verso do documento RNE ou RNM                                                                                                 |
| `CTPS_FRONT` | Frente do documento CTPS, onde a foto está localizada                                                                         |
| `CTPS_BACK`  | Verso do documento CTPS                                                                                                       |
| `PASSPORT`   | Documento de passaporte, exibindo a foto e os dados pessoais                                                                  |
| `ANY`        | Permite o envio de qualquer tipo de documento, incluindo todos os listados acima ou qualquer outro documento não classificado |

### Formatos de Arquivo Suportados (CafFileFormat)

| Tipo   | Valor             |
| ------ | ----------------- |
| `PNG`  | `image/png`       |
| `JPG`  | `image/jpg`       |
| `JPEG` | `image/jpeg`      |
| `PDF`  | `application/pdf` |
| `HEIF` | `image/heif`      |
| `HEIC` | `image/heic`      |

***

## Configuração Avançada

### Configuração da UI do Face Liveness

Ao usar o módulo de UI, você pode personalizar as telas de instrução:

```typescript
const { applyCafFaceLivenessUI } = useCafFaceLivenessUI();

// Aplique a configuração ao inicializar
await applyCafFaceLivenessUI({
  loading: true,
  authBaseUrl: "https://my.proxy.io/v1/faces/", 
  livenessBaseUrl: "wss://my.proxy.io/ws/",    
  certificates: [
    "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
    "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
    "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9=",
  ],
  screenCaptureEnabled: true,
  debugModeEnabled: true,
  executeFaceAuth: false, 
  maxRetryAttempts: 2,
  instructionScreen: {
    image: "scan_icon", // URL da imagem ou nome de um recurso local
    title: "Título personalizado",
    description: "Siga as etapas abaixo:",
    steps: ["Mantenha o telefone estável", "Garanta boa iluminação"],
    buttonText: "Iniciar leitura",
  },
});
```

### Configuração da UI do Detector de Documentos

```typescript
const { applyCafDocumentDetectorUI } = useCafDocumentDetectorUI();

// Aplique a configuração ao inicializar
await applyCafDocumentDetectorUI({
  flow: [{ document: CafDocument.RG_FRONT }], 
  manualCaptureEnabled: true,
  manualCaptureTime: 45,
  requestTimeout: 60,
  showPopup: true,
  securitySettings: {
    useDebug: true,
    useDevelopmentMode: true,
    useAdb: true,
  },
  maxRetryAttempts: 2,
  instructionScreen: {
    enable: true,
    captureTitle: "Capture seu documento",
    captureSteps: [
      "Mantenha o telefone estável",
      "Garanta boa iluminação",
      "Evite reflexos"
    ],
    buttonText: "Iniciar",
  },
  documentSelectionScreen: {
    title: "Selecione o tipo de documento",
    description: "Escolha qual documento você deseja enviar",
  },
});
```

### Configuração do Proxy

Para as configurações de proxy do Detector de Documentos:

```typescript
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Aplique a configuração ao inicializar
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  proxySettings: {
    hostname: "proxy.example.com",
    port: 8080,
    authentication: {
      user: "username",
      password: "password"
    }
  },
});
```

### Personalização de Mensagens

Personalize as mensagens exibidas durante o fluxo de captura:

```typescript
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Aplique a configuração ao inicializar
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  messageCustomization: {
    waitMessage: "Preparando a câmera...",
    fitTheDocumentMessage: "Posicione o documento dentro do enquadramento",
    holdItMessage: "Mantenha firme...",
    verifyingQualityMessage: "Verificando a qualidade do documento...",
    lowQualityDocumentMessage: "A qualidade do documento está muito baixa. Tente novamente.",
    uploadingImageMessage: "Enviando documento...",
    positiveButtonMessage: "Continuar",
  }
});
```

***

## Exemplo Completo de Implementação

Aqui está um exemplo completo mostrando tanto a UI do Face Liveness quanto a UI do Detector de Documentos:

```typescript
import React, { useEffect } from 'react';
import { SafeAreaView, View, Button, Text } from 'react-native';
import {
  useCafSdk,
  CafModuleType,
  CafEnvironment,
  CafDocument,
  CafFileFormat,
  useCafFaceLivenessUI,
  useCafDocumentDetectorUI,
} from '@caf.io/react-native-sdk';

function App(): React.JSX.Element {
  const { applyCafFaceLivenessUI } = useCafFaceLivenessUI();
  const { applyCafDocumentDetectorUI } = useCafDocumentDetectorUI();
  const { initialize, startSDK, loadSession, response, initialized } = useCafSdk();

  const handleInitialize = async () => {
    await initialize(
      {
        configuration: {
          presentationOrder: [
            CafModuleType.FACE_LIVENESS_UI,
            CafModuleType.DOCUMENT_DETECTOR_UI
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
          enableTransitionScreens: true,
          colorConfiguration: {
            primaryColor: "#007AFF",
            secondaryColor: "#34C759",
            backgroundColor: "#FFFFFF",
            contentColor: "#000000",
            mediumColor: "#8E8E93",
            dialogBackgroundColor: "#FFFFFF",
            dialogBorderColor: "#E5E5E7",
          },
        },
        mobileToken: 'your-mobile-token',
        environment: CafEnvironment.PROD,
        personId: 'user-person-id',
      },
      async () => {
        const appliedFaceLivenessUI = await applyCafFaceLivenessUI({
          maxRetryAttempts: 2,
          executeFaceAuth: true,
          debugModeEnabled: false,
          instructionScreen: {
            image: "face_scan_icon",
            title: "Verificação Facial",
            description: "Precisamos verificar sua identidade",
            steps: [
              "Posicione seu rosto no enquadramento",
              "Garanta boa iluminação",
              "Siga as instruções na tela"
            ],
            buttonText: "Iniciar verificação",
          },
        });
        const appliedDocumentDetectorUI = await applyCafDocumentDetectorUI({
          flow: [
            { document: CafDocument.RG_FRONT },
            { document: CafDocument.RG_BACK }
          ],
          manualCaptureEnabled: true,
          manualCaptureTime: 30,
          requestTimeout: 60,
          showPopup: true,
          maxRetryAttempts: 2,
          uploadSettings: {
            enable: true,
            compress: true,
            fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
            maxFileSize: 5, 
          },
          securitySettings: {
            useDebug: false,
            useDevelopmentMode: false,
            useAdb: false,
          },
          instructionScreen: {
            enable: true,
            captureTitle: "Captura de Documento",
            captureSteps: [
              "Mantenha o telefone estável",
              "Garanta boa iluminação",
              "Evite reflexos",
              "Encaixe o documento no enquadramento"
            ],
            buttonText: "Iniciar captura",
          },
          documentSelectionScreen: {
            title: "Selecione o tipo de documento",
            description: "Escolha o documento que deseja enviar",
          },
        });

        return appliedFaceLivenessUI && appliedDocumentDetectorUI;
      },
    ).then((result: boolean) => {
      if (result) {
        loadSession();
      }
    });
  };

  const handleStartSDK = () => {
    if (initialized) {
      startSDK();
    }
  };

  useEffect(() => {
    response.success?.forEach((item: CafSuccessResponse) => {
      if (item.moduleName === 'DOCUMENT_DETECTOR') {
        console.log(item.signedResponse);
      } else if (item.moduleName === 'FACE_LIVENESS') {
        console.log(item.signedResponse);
      }
    });
  }, [response]);

  useEffect(() => {
    if (response.error) {
      console.error('Erro do SDK:', response.error);
    }
  }, [response.error]);

  useEffect(() => {
    if (response.failure) {
      console.warn('Falha do SDK:', response.failure);
    }
  }, [response.failure]);

  useEffect(() => {
    if (response.log) {
      console.log('Log do SDK:', response.log);
    }
  }, [response.log]);

  useEffect(() => {
    handleInitialize();
  }, []);

  return (
    <SafeAreaView>
      <View style={{ padding: 20 }}>
        <Button 
          title="Iniciar verificação de identidade" 
          onPress={handleStartSDK}
          disabled={response.loading}
        />
        {response.loading && <Text>Processando...</Text>}
      </View>
    </SafeAreaView>
  );
}

export default App;
```

***

## Regras do ProGuard/R8

Adicione estas regras do ProGuard/R8 ao seu `proguard-rules.pro` arquivo para Android:

```proguard
### Regras do ProGuard/R8 para React Native do Caf SDK ########################
-dontobfuscate

-keep,allowobfuscation @interface com.facebook.proguard.annotations.DoNotStrip
-keep,allowobfuscation @interface com.facebook.proguard.annotations.KeepGettersAndSetters

-keep @com.facebook.proguard.annotations.DoNotStrip class *
-keepclassmembers class * {
    @com.facebook.proguard.annotations.DoNotStrip *;
}

-keepclassmembers @com.facebook.proguard.annotations.KeepGettersAndSetters class * {
  void set*(***);
  *** get*();
}

-keep class * extends com.facebook.react.bridge.JavaScriptModule { *; }
-keep class * extends com.facebook.react.bridge.NativeModule { *; }

-keepclassmembers,includedescriptorclasses class * { native <methods>; }
-keepclassmembers class *  { @com.facebook.react.uimanager.annotations.ReactProp <methods>; }
-keepclassmembers class *  { @com.facebook.react.uimanager.annotations.ReactPropGroup <methods>; }
-dontwarn com.facebook.react.**
### FIM das regras do React Native ProGuard/R8 #############################

### GSON ##################################################################
# O Gson usa informações genéricas de tipo armazenadas em um arquivo de classe ao trabalhar com campos.
# O ProGuard remove essas informações por padrão, então configure-o para manter todas elas.
-keepattributes Signature
# Para usar a anotação @Expose do GSON
-keepattributes *Annotation*
### FIM GSON ##################################################################

### Retrofit ##################################################################
# Preserva assinaturas genéricas, classes internas e métodos envolventes para a reflexão do Retrofit.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Mantém anotações visíveis em tempo de execução em métodos e parâmetros.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Mantém os valores padrão das anotações.
-keepattributes AnnotationDefault
# Mantém os parâmetros dos métodos de serviço para interfaces com anotações do Retrofit.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suprime avisos para ferramentas de build e certas anotações JSR 305.
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
# Mantém explicitamente as interfaces do Retrofit para evitar a nulificação pelo R8.
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
# Preserva as continuations usadas por funções suspend do Kotlin.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# Para o modo completo do R8: mantém os tipos genéricos de retorno para métodos do Retrofit.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preserva a classe Response do Retrofit.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### FIM Retrofit ##############################################################

### OkHttp ####################################################################
# Suprime avisos para anotações JSR 305.
-dontwarn javax.annotation.**
# Adapta os nomes de arquivos de recursos para o banco de dados interno de sufixos públicos.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suprime avisos para o Animal Sniffer e classes específicas da plataforma.
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
# Mantém todas as classes do OkHttp e do Okio.
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### FIM OkHttp ################################################################

### Serialização Kotlin ######################################################
# Mantém os objetos Companion para classes serializáveis.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Mantém funções serializer nos objetos companion.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Mantém INSTANCE e serializer para objetos serializáveis.
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserva objetos Companion em kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserva a busca do serializer para classes serializáveis (ajuste o nome do pacote conforme necessário).
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### FIM Serialização Kotlin #################################################

### AutoValue ################################################################
-dontwarn com.google.auto.**
-dontwarn autovalue.shaded.com.**
-dontwarn sun.misc.Unsafe
-dontwarn javax.lang.model.element.Modifier
### FIM AutoValue ############################################################

### CAF - Combate a Fraude ############################################## 
# Mantém atributos de exceções.
-keepattributes Exceptions
# Preserva todas as classes, interfaces e membros de classe para os módulos CAF.
-keep class com.caf.facelivenessiproov.** { *; }
-keep class com.combateafraude.documentdetector.** { *; }
-keep class com.combateafraude.** { *; }
-keep interface com.combateafraude.** { *; }
-keep class io.caf.** { *; }
-keep interface io.caf.** { *; }
-keepclassmembers class com.combateafraude.** { *; }
# Suprime avisos para java.nio.file e certas classes internas do OkHttp.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Mantém campos em classes que estendem GeneratedMessageLite (para uso com Tink).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preserva classes do TensorFlow.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preserva classes do IProov e classes do Protobuf.
-keep public class com.iproov.sdk.IProov { public *; }
-keep class com.iproov.** { *; }
-keep class com.iproov.**$* { *; }
-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }
-dontwarn com.google.protobuf.**
# Suprime avisos para classes Flow concorrentes.
-dontwarn java.util.concurrent.Flow*
# Preserva classes Kotlin e kotlinx.
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### FIM CAF - Combate a Fraude #########################################
```

***

## Suporte Técnico e Dicas de Uso

**Suporte Técnico** Se você tiver dúvidas ou dificuldades com a integração, entre em contato com o suporte técnico da Caf.

**Dicas de uso**

* **Execute testes:** Faça testes em dispositivos reais para validar os requisitos e o desempenho do fluxo
* **Explore personalizações:** Use opções avançadas de personalização para adaptar o fluxo às necessidades do seu projeto
* **Monitore o desempenho:** Integre ferramentas de monitoramento para acompanhar logs e o desempenho do fluxo em produção
* **Lide com erros com elegância:** Implemente o tratamento adequado de erros para todos os possíveis cenários de erro e falha
* **Teste com diferentes dispositivos:** Garanta compatibilidade entre várias especificações de dispositivos e tamanhos de tela

***

## Problemas conhecidos

### Falha: os fragmentos de tela nunca devem ser restaurados

#### Descrição

Em aplicativos React Native que consomem SDKs nativos do Android, uma falha pode ocorrer quando o sistema operacional recria a Activity principal após ela ter sido destruída em segundo plano. O erro típico exibido é:

```
java.lang.IllegalStateException: os fragmentos de tela nunca devem ser restaurados
```

#### Contexto

O Android pode encerrar processos em segundo plano para liberar recursos do sistema. Quando o usuário retorna ao aplicativo, o sistema tenta restaurar o estado anterior da Activity, incluindo os fragmentos de tela. A `react-native-screens` biblioteca, usada para gerenciamento de navegação, não oferece suporte a esse comportamento por padrão e lança uma exceção.

#### Solução

Adicione a seguinte sobrescrita ao arquivo `MainActivity.kt` do seu projeto, conforme recomendado na `react-native-screens` documentação:

```kotlin
package com.your.app

import android.os.Bundle;
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;

class MainActivity : ReactActivity() {

  //...code

  override fun onCreate(savedInstanceState: Bundle?) {
      supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
      super.onCreate(savedInstanceState);
  }

  //...code
}
```

Ao definir `RNScreensFragmentFactory` como a fábrica de fragmentos antes de chamar `super.onCreate()`, a biblioteca pode lidar corretamente com a restauração de fragmentos quando a Activity é recriada.

#### Impacto

Essa alteração permite que o aplicativo lide com cenários de recriação da Activity com elegância, sem travar, mantendo uma experiência de usuário contínua mesmo quando o sistema recupera recursos em segundo plano.

***

## Notas de versão

### @caf.io/react-native-sdk\@5.2.0

#### **Data de lançamento**

* 08/14/2026

#### **Destaques**

* **Compatibilidade com Android 16:** Módulo React Native atualizado para suportar Android 16 (`compileSdk` / `targetSdk` 36), em conformidade com os requisitos do Google Play para apps direcionados a versões recentes do Android.

#### **Correções**

**Face Liveness:** Corrigido um problema no fluxo Payface em que uma validação de face com falha ainda podia ser reportada como sucesso. Agora o SDK trata corretamente as falhas de validação e mostra a mensagem apropriada ao usuário.

**Document Detector:** Corrigidos problemas de captura e upload em tablets e dispositivos no modo paisagem, incluindo um breve flash de orientação de imagem incorreta na pré-visualização, falhas de captura automática com fotos finais desalinhadas e pequenos ajustes de UI nas margens do layout e no botão de fechar.

#### **Atualizações**

* Módulo Android do React Native `compileSdk` / `targetSdk` atualizado para **36**.

### @caf.io/react-native-sdk\@5.1.0

#### Data de lançamento

* 08-03-2026

{% hint style="warning" %}
**Mudança que quebra compatibilidade:** O módulo Fingerprint agora é opcional e pode ser configurado em `caf-modules-config.json` por meio da nova `fingerprint` propriedade (boolean). Por padrão, Fingerprint está definido como `false`, o que significa que você não precisa adicionar essa propriedade ao JSON, a menos que queira usá-la. Para habilitar o módulo, você deve adicionar explicitamente `"fingerprint": true`. Importante: Fingerprint também deve estar ativado no Backoffice. Se ele não estiver ativado no Backoffice, o SDK nunca chamará a biblioteca de fingerprint e nenhum dado será enviado, mesmo que a propriedade esteja definida como `true` localmente.&#x20;
{% endhint %}

#### Destaques

* **Módulo Fingerprint opcional:** Controle a inclusão do recurso de fingerprint diretamente a partir de `caf-modules-config.json`. Ele é desativado por padrão, garantindo que você inclua a dependência somente quando estritamente necessário.

#### Atualizações

* Novo `fingerprint` campo booleano em `caf-modules-config.json` para Android e iOS.

```json
{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": [
    "iproov-lite",
    "payface",
    "facetec"
  ],
  "fingerprint": true
}
```

### @caf.io/react-native-sdk\@5.0.0

#### Data de lançamento

* 07-06-2026

#### Mudanças que quebram compatibilidade

O intermediário `configuração` objeto wrapper foi **removido** de todos os hooks de módulos independentes. Os campos de configuração agora são passados **diretamente** no objeto.

Hooks afetados:

* `applyCafDocumentDetector()`
* `applyCafDocumentDetectorUI()`
* `applyCafFaceLiveness()`
* `applyCafFaceLivenessUI()`

```tsx
// Antes (4.x)
await applyCafFaceLiveness({
  configuration: { loading: false, maxRetryAttempts: 0 },
});

// Depois (5.0.0)
await applyCafFaceLiveness({
  loading: false,
  maxRetryAttempts: 0,
});
```

**Tipos de configuração renomeados**

O `BuilderConfiguration` interfaces foram removidas. Os tipos públicos de configuração agora são as `Configuração` interfaces:

| Removido (4.x)                                                     | Usar em vez disso (5.0.0)                                   |
| ------------------------------------------------------------------ | ----------------------------------------------------------- |
| `CafDocumentDetectorBuilderConfiguration`                          | `CafDocumentDetectorConfiguration`                          |
| `CafFaceLivenessBuilderConfiguration`                              | `CafFaceLivenessConfiguration`                              |
| `CafDocumentDetectorUIBuilderInstructionScreenConfiguration`       | `CafDocumentDetectorUIInstructionScreenConfiguration`       |
| `CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration` | `CafDocumentDetectorUIDocumentSelectionScreenConfiguration` |
| `CafFaceLivenessUIBuilderInstructionScreenConfiguration`           | `CafFaceLivenessUIInstructionScreenConfiguration`           |

`CafDocumentDetectorConfiguration` e `CafFaceLivenessConfiguration` não são mais wrappers em torno de um `configuração` aninhado — agora elas contêm os campos diretamente. `CafDocumentDetectorUIConfiguration` e `CafFaceLivenessUIConfiguration` agora **estendem** a configuração base em vez de aninhá-la.

**Campos de configuração de UI renomeados**

| Campo removido (4.x)                   | Usar em vez disso (5.0.0) |
| -------------------------------------- | ------------------------- |
| `instructionScreenConfiguration`       | `instructionScreen`       |
| `documentSelectionScreenConfiguration` | `documentSelectionScreen` |

**Comportamento do estado da resposta**

O `useCafSdk` o ciclo de vida da response mudou e pode exigir ajustes se você dependia dos resets implícitos de estado anteriores:

* `initialize()` agora **redefine** o `response` objeto (`sucesso`, `falha`, `erro`, `cancelado`, `registro`, `carregamento`) no início de cada chamada.
* O `Sucesso`, `Falha`, `Erro`, e `Cancelado` eventos agora todos definem `initialized` de volta para `false`.
* O `Carregando` e `Carregado` eventos **não limpam mais** `sucesso` / `falha` / `erro` / `cancelado` — eles apenas atualizam o `carregamento` sinalizador.

#### Recursos

* **Novo tipo de erro `CafErrorType.BRIDGE_EXCEPTION`:** emitido quando a ponte recebe um payload JSON inválido/vazio ou falha ao mapear a configuração, em vez de falhar silenciosamente.
* **Alternância da tela de instruções para a UI do Face Liveness:** novo opcional `enable?: boolean` (padrão `true`) em `CafFaceLivenessUIInstructionScreenConfiguration`, correspondendo à tela de instruções da UI do Document Detector.

#### Guia de migração - 4.x → 5.0.0

O contrato público da ponte (nomes de métodos nativos, nomes de eventos como `CafUnifiedEvent.*`, e chaves de payload de resposta como `moduleName` / `signedResponse`) está **inalterado**. O único trabalho de migração é nos **objetos de configuração do TypeScript** que você passa para os hooks do módulo.

#### 1. Remova o `configuração` wrapper

Retire cada campo do `configuração` objeto e passe-o diretamente.

**Document Detector**

```tsx
// Antes (4.x)
await applyCafDocumentDetector({
  configuration: {
    flow: [{ document: CafDocument.RG_FRONT }],
    manualCaptureEnabled: false,
    maxRetryAttempts: 0,
  },
});

// Depois (5.0.0)
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  manualCaptureEnabled: false,
  maxRetryAttempts: 0,
});
```

**Face Liveness**

```tsx
// Antes (4.x)
await applyCafFaceLiveness({
  configuration: { loading: false, maxRetryAttempts: 0 },
});

// Depois (5.0.0)
await applyCafFaceLiveness({
  loading: false,
  maxRetryAttempts: 0,
});
```

#### 2. Atualize os hooks de UI (config + campos renomeados)

**UI do Document Detector**

```tsx
// Antes (4.x)
await applyCafDocumentDetectorUI({
  configuration: { flow: [{ document: CafDocument.RG_FRONT }] },
  instructionScreenConfiguration: { enable: true, title: 'Capture' },
  documentSelectionScreenConfiguration: { title: 'Choose document' },
});

// Depois (5.0.0)
await applyCafDocumentDetectorUI({
  flow: [{ document: CafDocument.RG_FRONT }],
  instructionScreen: { enable: true, title: 'Capture' },
  documentSelectionScreen: { title: 'Choose document' },
});
```

**UI do Face Liveness**

```tsx
// Antes (4.x)
await applyCafFaceLivenessUI({
  configuration: { loading: false },
  instructionScreenConfiguration: { title: 'Vivacidade facial' },
});

// Depois (5.0.0)
await applyCafFaceLivenessUI({
  loading: false,
  instructionScreen: { enable: true, title: 'Vivacidade facial' },
});
```

#### 3. Atualize suas importações de tipos

Se você importou algum dos tipos removidos, renomeie-os:

```tsx
// Antes (4.x)
import type {
  CafDocumentDetectorBuilderConfiguration,
  CafFaceLivenessBuilderConfiguration,
  CafDocumentDetectorUIBuilderInstructionScreenConfiguration,
  CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration,
  CafFaceLivenessUIBuilderInstructionScreenConfiguration,
} from '@caf.io/react-native-sdk';

// Depois (5.0.0)
import type {
  CafDocumentDetectorConfiguration,
  CafFaceLivenessConfiguration,
  CafDocumentDetectorUIInstructionScreenConfiguration,
  CafDocumentDetectorUIDocumentSelectionScreenConfiguration,
  CafFaceLivenessUIInstructionScreenConfiguration,
} from '@caf.io/react-native-sdk';
```

#### 4. Revise o tratamento das suas respostas (opcional)

Se seu app dependia do antigo efeito colateral em que um `Carregando` / `Carregado` evento limpava `sucesso` / `falha` / `erro`, trate essas redefinições explicitamente. Observe que `initialize()` agora limpa o `response` no início de cada execução.

### @caf.io/react-native-sdk\@4.5.2

#### Data de lançamento

* 07-20-2026

#### Correções

* Condições de corrida durante o retorno do Evento de Sucesso

### @caf.io/react-native-sdk\@4.5.1

#### Data de lançamento

* 06-10-2026

#### Correções

* Maven CDN Fortface não encontrado

### @caf.io/react-native-sdk\@4.4.1

#### Data de lançamento

* 06-10-2026

#### Correções

* Maven CDN Fortface não encontrado

### @caf.io/react-native-sdk\@4.3.1

#### Data de lançamento

* 06-10-2026

#### Correções

* Maven CDN Fortface não encontrado

### @caf.io/react-native-sdk\@4.5.0

#### Data de lançamento

* 06-09-2026

#### Atualizações

* **Provedor de Vivacidade Payface (Android)**: Atualize a versão de `1.18.2` para `1.19.2`.
* **Provedor de Vivacidade Payface (iOS)**: Atualize a versão de `1.5.2` para `1.8.2`.

#### Correções

**FaceLiveness**

* O erro de carregamento infinito ocorre quando o SDK retorna um erro.
* A primeira inicialização não funciona ao usar `Payface` provedor.

### @caf.io/react-native-sdk\@4.4.0

#### Data de lançamento

* 04-27-2026

{% hint style="warning" %}
**Mudança que quebra compatibilidade:** Os provedores de Face Liveness agora podem ser configurados em `caf-modules-config.json` via **`livenessProviders`** (string ou array). Quando fornecido, deve listar o(s) provedor(es) escolhido(s). Não use **`iproov-lite`** e **`iproov-full`** juntos —**`iproov-full`** usa uma versão diferente do Protobuf, e combiná-los causará erros de classes duplicadas em tempo de build. **PayFace** requer **`iproov-lite`** (Protobuf JavaLite); emparelhar PayFace com **`iproov-full`** causa conflitos de Protobuf em tempo de build. Se omitido, o SDK usa como padrão **`iproov-lite`** em ambas as plataformas. Um **valor vazio ou inválido** causa um erro de build no **Android**; no **iOS**, um valor vazio também recorre a `iproov-lite`, mas um valor inválido causa falha de build. Veja [Passo 2: Configure a seleção de módulos](#step-2-configure-module-selection) para mais detalhes.
{% endhint %}

#### Recursos

* **Provedores configuráveis de Face Liveness**: Escolha `iproov-lite`, `iproov-full`, `payface`, e/ou `facetec` de `caf-modules-config.json` em vez de depender dos padrões nativos implícitos.

#### Atualizações

* **Configuração do provedor de Liveness**:
  * Novo **`livenessProviders`** campo em `caf-modules-config.json` para Android e iOS.
  * Documentado **Protobuf JavaLite** vs **Protobuf Java** mapeamento para **`iproov-lite`** vs **`iproov-full`**.
  * Esclarecido **multi-provedor** configurações usando um array, e o **PayFace + iProov Lite** requisito.
* **Provedor de Vivacidade iProov**: A documentação e os padrões foram atualizados para refletir o novo modelo de seleção de provedor.
* **Android ProGuard / R8**: Se o R8 relatar classes ausentes para stubs de lint enviados com o SDK, adicione o seguinte a `proguard-rules.pro` (também listado em [Regras do ProGuard/R8](#proguardr8-rules)):

```proguard
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
```

### @caf.io/react-native-sdk\@4.3.0

{% hint style="warning" %}
Versões anteriores à 4.3.0 farão com que o iProov Liveness se torne inoperante em 12 de março de 2026. Para garantir o funcionamento adequado e a continuidade do serviço, use a versão 4.3.0 ou posterior.
{% endhint %}

#### Data de lançamento

* 02/09/2026

#### Atualização

* Atualização de dependência: versão do iProov atualizada de 10.2.0 para 11.1.0 no Android.
* Atualização de dependência: versão do iProov atualizada de 12.2.1 para 13.1.0 no iOS.

**Android e iOS**

* Novos tipos de falha: nova falha adicionada a CafFailureType para melhor tratamento de falhas:
  * `BACKGROUND_ISSUE`
  * `DEVICE_ISSUE`
  * `EYEWEAR`
  * `FACE_NOT_FOUND`
  * `FRAMES_BLURRY`
  * `MOTION_ISSUE`
  * `LIGHTING_ISSUES`
  * `REJECTED`
  * `SYSTEM_ERROR`
  * `TIMEOUT`
  * `USER_NOT_FOUND`
  * `DEVICE_RESTART`
  * `PROCESSING_FAULT`

### @caf.io/react-native-sdk\@4.2.0

#### Data de lançamento

* 02/02/2026

#### Recursos

* **Novo módulo CafSecurity**: Adicionado um novo módulo com validações de segurança.
  * Nova flag de configuração: `enableSecurityModule` em `CafSdkConfiguration` com valor padrão `true`

#### Correções

* **FaceLiveness**
  * Corrigidos erros na criação de sessões.
  * Corrigido o tom de cor em imagens remotas na tela de Instruções.

### @caf.io/react-native-sdk\@4.1.1

#### Data de lançamento

* 01/12/2026

#### Recursos

* **Integração do Provedor PayFace (Fortface):** Provedor opcional de Face Liveness agora disponível
  * Nova propriedade `payFaceDebugMode` em `CafFaceLivenessConfig` para ativar o modo de depuração para o provedor PayFace.

#### Correções

* **Corrigidos travamentos no módulo Document Detector**: Resolvidos vários travamentos relacionados ao gerenciamento do ciclo de vida da atividade, incluindo os estados de inicialização, pausa e retomada.
* **Corrigidos travamentos relacionados ao ciclo de vida da câmera**: Melhorado o gerenciamento de recursos da câmera e do ciclo de vida das threads para evitar travamentos durante o encerramento do SDK e transições de estado.
* **Corrigidos travamentos em componentes de UI**: Resolvidos problemas de compatibilidade de tema e exceções de transação de fragmentos para garantir o comportamento adequado da UI.
* **Corrigidos travamentos em requisições de rede**: Corrigido o tratamento do corpo da resposta para evitar erros ao ler respostas de rede.
* **Corrigidos travamentos no acesso a dados**: Melhorada a inicialização e a validação do cursor antes de acessar dados do banco de dados.
* **Corrigido ANR no Document Controller**: Otimizadas as verificações de instância do controlador de documentos para evitar problemas de aplicativo não respondendo.
* **Melhorias e correções internas**: Aprimoramentos adicionais de estabilidade e correções de bugs.

### @caf.io/react-native-sdk\@4.0.0

#### Data de lançamento

* 11/27/2025

#### Mudanças que quebram compatibilidade

**Prevenção de condição de corrida:**

Para evitar condições de corrida, as seguintes funções agora retornam `Promise<boolean>`:

* **`initialize()`**: Agora retorna `Promise<boolean>`. O parâmetro de callback também retorna `Promise<boolean>`.
* **`applyCafFaceLiveness()`**: Agora retorna `Promise<boolean>`.
* **`applyCafFaceLivenessUI()`**: Agora retorna `Promise<boolean>`.

**Novo estado: `initialized`**

Um novo `initialized` estado é retornado do `useCafSdk` hook. Este estado permite verificar se a `initialize` função aplicou com sucesso as configurações do módulo.

As configurações dos módulos agora são definidas nas funções `initialize`, `applyCafDocumentDetector`, `applyCafFaceLiveness`, `applyCafDocumentDetectorUI`, `applyCafFaceLivenessUI`.

**Exemplo de migração:**

```typescript
const { initialize, initialized } = useCafSdk();
const { applyCafDocumentDetector } = useCafDocumentDetector();
const { applyCafFaceLiveness } = useCafFaceLiveness();

function handleInitialize() {
  initialize(
    {
      environment: config.environment,
      mobileToken: config.mobileToken,
      personId: config.personId,
      configuration: {
        presentationOrder: [CafModuleType.DOCUMENT_DETECTOR, CafModuleType.FACE_LIVENESS],
        enableSecurityModule: true,
      },
    },
    async () => {
      const appliedDocumentDetectorSettings = await applyCafDocumentDetector({
        configuration: {
          flow: [{ document: CafDocument.RG_FRONT }],
          manualCaptureEnabled: false,
          securitySettings: {
            useAdb: true,
            useDebug: true,
            useDevelopmentMode: true,
          },
          maxRetryAttempts: 0,
        },
      });
      
      const appliedFaceLivenessSettings = await applyCafFaceLiveness({
        configuration: {
          loading: false,
          debugModeEnabled: true,
          maxRetryAttempts: 0,
        },
      });
      
      return appliedDocumentDetectorSettings && appliedFaceLivenessSettings;
    },
  ).then((res: boolean) => {
    if (res) {
      // loadSession();
      // startSDK();
    }
  });
}
```

#### Correções

**Detector de Documentos / UI do Detector de Documentos**

* **Corrigido o crash ao usar fluxo vazio `flow` em `CafDocumentDetectorConfig`**: Esse problema fazia o SDK fechar imediatamente durante a abertura do fluxo de captura de documentos. Agora o SDK emitirá um novo evento de erro `CafErrorType.LIBRARY_EXCEPTION` com a mensagem "Empty document options".
* **Corrigido erro ao usar `loadSession` no módulo Document Detector**: Esse problema fazia o SDK fechar imediatamente durante a abertura do fluxo de captura de documentos. Agora o sdk não emitirá um erro `SEQUENCE_INVALID`.

### @caf.io/react-native-sdk\@3.0.0

#### Data de lançamento

* 11/17/2025

#### Recursos

**Inicialização do SDK**

* **Novos métodos:**
  * `loadSession()`: Pré-carrega a sessão do usuário antes de iniciar o fluxo do SDK. Isso melhora o tempo de abertura do SDK ao preparar a sessão e a inicialização da câmera com antecedência, resultando em uma inicialização mais rápida do SDK quando `start()` for chamado. Este método é opcional e pode ser chamado após `initialize()` mas antes de `start()`.
  * `start()`: Inicia o fluxo do SDK depois que a configuração foi criada. Este método inicia a execução sequencial dos módulos configurados.

**Resposta**

* **Nova resposta:**
  * `response.success`: Um array de `CafSuccessResponse` objetos.

**Detector de Documentos / UI do Detector de Documentos**

**Android**

* **Modo de captura manual como padrão**: O modo de captura manual desde o início agora é o padrão, devido às dificuldades de captura usando o modo automático.
* **Logs de analytics**: Adicionados logs detalhados de analytics para monitorar detalhes da captura e do upload de documentos. Esses logs registram mensagens, modos de captura, tempo de fallback e sensores.

**iOS**

* **Modo de captura manual como padrão**: O modo de captura manual desde o início agora é o padrão, devido às dificuldades de captura usando o modo automático.

#### Mudanças que quebram compatibilidade

* **Fluxo de inicialização do SDK:**
  * Antes, `initialize()` iniciava automaticamente o SDK após criar as configurações.
  * Agora, `initialize()` apenas cria as configurações do SDK e não inicia o SDK automaticamente.
  * Você deve chamar explicitamente `startSDK()` após `initialize()` para realmente iniciar o fluxo do SDK.
  * O fluxo recomendado é: `initialize()` → (opcional) `loadSession()` → `startSDK()`

#### Correções

**Detector de Documentos / UI do Detector de Documentos**

**Android**

* **Corrigido crash "Image is already closed"**: Esse problema fazia o SDK fechar imediatamente durante a captura de documentos.
* **Corrigido o crash ao usar fluxo vazio `flow` em `CafDocumentDetectorConfig`**: Esse problema fazia o SDK fechar imediatamente durante a abertura do fluxo de captura de documentos. Agora o SDK emitirá um novo evento de erro `CafErrorType.LIBRARY_EXCEPTION` com a mensagem "Empty document options".
* **Mensagens de erro aprimoradas**: Mensagens de erro aprimoradas para detecção incorreta do tipo de documento, oferecendo feedback mais preciso durante a validação do documento.
* **Fallback no modo de captura**: Melhorado o gerenciamento de estado nas transições do modo de captura para garantir um comportamento consistente e confiável quando os modos de captura manual e automática interagem.
* **Layout**: Melhorada a legibilidade com maior espaçamento entre linhas e margens atualizadas para um layout e um equilíbrio visual mais consistentes.
* **Melhorias na UI**: Evitado estouro de texto no detector de documentos ao habilitar truncamento para títulos longos e nomes de etapas e ajustar o espaçamento.
* **Desativação do sensor de luz**: O sensor de luz foi desativado durante o fluxo de captura. Anteriormente, o SDK usava o sensor de luz do dispositivo para exibir a mensagem "Environment too dark", bloqueando a captura até o sensor detectar boa iluminação.
* **Desativação de mensagens durante a captura manual**: As mensagens durante a captura manual foram desativadas para evitar atritos durante o fluxo de captura.

**iOS**

* **Mensagens de erro**: Mensagens de erro aprimoradas para detecção incorreta do tipo de documento, oferecendo feedback mais preciso durante a validação do documento.
* **Relatório de atestação**: Relatório de erros de atestação mais detalhado (rede/token inválido/resposta inválida) com tratamento de erro mais seguro.
* **Identificação de documento**: Corrigido o problema em que a identificação do documento não era exibida na tela de captura de imagem mesmo sem configuração personalizada.

### @caf.io/react-native-sdk\@2.1.0

### Data de lançamento

* 10/15/2025

#### Destaques

* **Suporte a tamanho de página de 16 KB no Android**

#### Recursos

* **Rótulos de grupo**: Rótulos de grupo opcionais na tela de Seleção de Documento para mostrar títulos e descrições personalizados por grupo de documentos (RG, CNH, Passaporte etc.).

#### Correções

**Android**

* **Melhorias em analytics**: Melhorado o relatório de erros em todos os fluxos de vivacidade facial: distinções mais claras entre rede/servidor, tratamento preciso de permissões da câmera.
* **DocumentDetector**: parou de habilitar automaticamente a visualização do documento quando não configurada explicitamente.

### @caf.io/react-native-sdk\@2.0.0

#### Destaques

* **SDK unificado**: Consolidação completa de todos os módulos CAF em um único pacote, eliminando a necessidade de várias dependências separadas
* **Integração simplificada**: Processo de instalação e configuração simplificado com gerenciamento unificado de módulos
* **Suporte aprimorado ao TypeScript**: Todas as definições de tipos consolidadas no pacote principal do SDK para uma melhor experiência de desenvolvimento
* **Configuração de módulos**: Adicionado um sistema abrangente de configuração de módulos para uma configuração flexível do SDK

#### Mudanças que quebram compatibilidade

* **Consolidação de dependências**: Os seguintes pacotes não são mais necessários e devem ser removidos do seu projeto:
  * `@caf.io/react-native-face-liveness`
  * `@caf.io/react-native-face-liveness-ui`
  * `@caf.io/react-native-document-detector`
  * `@caf.io/react-native-document-detector-ui`
* **Migração das definições de tipos**: Todos os tipos do TypeScript foram movidos para `@caf.io/react-native-sdk`
  * Remova as importações de tipos dos pacotes individuais
  * Importe todos os tipos de `@caf.io/react-native-sdk`
* **Configuração de módulos**: Novo sistema de configuração usando `caf-modules-config.json` arquivo
  * Os módulos devem ser explicitamente ativados/desativados no arquivo de configuração
  * Se nenhum arquivo de configuração for fornecido, todos os módulos serão incluídos por padrão

#### Recursos

* **Sistema de configuração de módulos**:
  * **`caf-modules-config.json`**: Novo arquivo de configuração na raiz do projeto para especificar quais módulos incluir
  * Módulos disponíveis:
    * `documentDetector`: Ativar/desativar o módulo Document Detector
    * `faceLiveness`: Ativar/desativar o módulo Face Liveness
    * `documentDetectorUI`: Ativar/desativar o módulo UI do Document Detector
    * `faceLivenessUI`: Ativar/desativar o módulo UI do Face Liveness
  * Exemplo de configuração:

    ```json
    {
      "documentDetector": true,
      "faceLiveness": true,
      "documentDetectorUI": false,
      "faceLivenessUI": false
    }
    ```
* **Tratamento unificado de erros**: Tratamento consistente de erros em todos os módulos
* **Desempenho aprimorado**: Tamanho do bundle e desempenho em runtime otimizados por meio da inclusão seletiva de módulos
* **Analytics aprimorados**: Rastreamento de analytics unificado em todos os módulos

#### Correções

**iOS**

* **Correção de condição de corrida**: Resolvida uma condição de corrida que impedia a abertura do SDK em dispositivos iOS
* **Gerenciamento de memória**: Melhorado o tratamento de memória durante as transições de módulo
* **Problemas de navegação**: Corrigidos problemas de navegação aninhada no iOS

**Android**

* **Tratamento de permissões**: Relato aprimorado de erros de permissão da câmera com classificação distinta de erros
* **Estabilidade da rede**: Melhorado o tratamento de erros de rede e os mecanismos de repetição
* **Compatibilidade de build**: Configurações de build atualizadas para melhor compatibilidade

**Multiplataforma**

* **Relato de erros**: Maior clareza nas mensagens de erro do servidor ao extrair e exibir cargas brutas de erro
* **Estados de carregamento**: Melhor comportamento da tela de carregamento e gerenciamento de estado
* **Ciclo de vida do módulo**: Melhor tratamento da inicialização e limpeza dos módulos

#### Guia de migração

Para migrar de pacotes individuais para o SDK unificado:

1. **Remova as dependências antigas**:

   ```bash
   npm uninstall @caf.io/react-native-face-liveness @caf.io/react-native-face-liveness-ui @caf.io/react-native-document-detector @caf.io/react-native-document-detector-ui
   ```
2. **Instale o SDK unificado**:

   ```bash
   npm install @caf.io/react-native-sdk@2.0.0
   ```
3. **Crie o arquivo de configuração de módulos**: Crie `caf-modules-config.json` na raiz do seu projeto:

   ```json
   {
     "documentDetector": true,
     "faceLiveness": true,
     "documentDetectorUI": false,
     "faceLivenessUI": false
   }
   ```
4. **Atualize as importações**:

   ```typescript
   // Antes
   import { useCafFaceLiveness } from '@caf.io/react-native-face-liveness';
   import { useCafDocumentDetector } from '@caf.io/react-native-document-detector';

   // Depois
   import { 
     useCafFaceLiveness, 
     useCafDocumentDetector 
   } from '@caf.io/react-native-sdk';
   ```
5. **A implementação permanece a mesma**: Seu código de implementação existente não precisa ser alterado. Os hooks e seu uso continuam idênticos:

   ```typescript
   // Este código funciona exatamente da mesma forma que antes
   const { applyCafFaceLiveness } = useCafFaceLiveness(settings);
   const { applyCafDocumentDetector } = useCafDocumentDetector(settings);
   ```

### @caf.io/react-native-sdk\@1.1.0

#### Novos recursos

* **Novos tipos:**
  * `CafErrorType` e `CafFailureType` enums adicionados ao SDK
* **Novas propriedades:**
  * `CafSdkBuilderConfiguration` agora tem `enableTransitionScreens` propriedade para ativar/desativar telas de transição entre módulos
  * `CafColorConfiguration` agora tem `dialogBackgroundColor` e `dialogBorderColor` propriedades para personalização do diálogo

### @caf.io/react-native-face-liveness\@4.1.0

#### Novos recursos

* **Melhorias Internas:** Tratamento interno aprimorado dos fluxos de captura de documentos, melhorando o desempenho e a confiabilidade

### @caf.io/react-native-face-liveness-ui\@1.1.0

#### Novos recursos

* **Melhorias Internas:** Tratamento interno aprimorado dos fluxos de captura de documentos, melhorando o desempenho e a confiabilidade

### @caf.io/react-native-document-detector\@4.1.0

#### Novos recursos

* **Melhorias Internas:** Tratamento interno aprimorado dos fluxos de captura de documentos, melhorando o desempenho e a confiabilidade

### @caf.io/react-native-document-detector-ui\@1.1.0

#### Novos recursos

* **Novas propriedades:**
  * `CafDocumentDetectorUIBuilderInstructionScreenConfiguration` agora tem `habilitar` propriedade para personalizar a tela de instruções

### @caf.io/react-native-sdk\@1.0.0

#### Novos recursos

* **Implementação:** Novo `executeFaceAuth` propriedade nos módulos Face Liveness para um controle mais granular sobre a autenticação facial

### @caf.io/react-native-face-liveness\@4.0.0

#### Novos recursos

* **Nova Propriedade:** `executeFaceAuth` propriedade permite um controle mais granular sobre o processo de autenticação facial

### @caf.io/react-native-face-liveness-ui\@1.0.0

#### Novos recursos

* **Nova Propriedade:** `executeFaceAuth` propriedade permite um controle mais granular sobre o processo de autenticação facial

### @caf.io/react-native-document-detector\@4.0.0

#### Novos recursos

* **Melhorias Internas:** Tratamento interno aprimorado dos fluxos de captura de documentos, melhorando o desempenho e a confiabilidade

### @caf.io/react-native-document-detector-ui\@1.0.0

#### Novos recursos

* **Melhorias Internas:** Tratamento interno aprimorado dos fluxos de captura de documentos, melhorando o desempenho e a confiabilidade

### @caf.io/react-native-sdk\@1.0.0-beta1

#### Novos recursos

* **Apresentando `@caf.io/react-native-sdk`:** Um SDK unificado para integrar os módulos Face Liveness e Document Detector em aplicações React Native
* **Suporte ao Padrão Builder:** Configuração simplificada usando `CafSdkBuilderConfiguration`, permitindo configuração com segurança de tipos e composição modular
* **Modelo de Configuração Unificado:** Gerencie a ordem de execução (`presentationOrder`), a temática da interface (`CafColorConfiguration`), e o comportamento do fluxo de forma centralizada
* **Tratamento Consistente dos Módulos:** Autenticação compartilhada, ambiente (`CafEnvironment`), logs (`CafLog`), e estrutura de resposta em todos os módulos
* **Integração Simplificada:** Hook React para inicializar e gerenciar todo o ciclo de vida do SDK
* **Rastreamento de Estado em Tempo Real:** Fornece um `response` objeto unificado com atualizações em tempo real sobre carregamento, cancelamento, sucesso, falha e logs
* **Acionamento Manual:** Expõe `initialize()` para iniciar o fluxo após a configuração nativa ser concluída
* **Gerenciamento de Eventos Integrado:** Escuta e reage a todas as emissões de `CafUnifiedEvent` , abstraindo a camada de comunicação nativa

#### Tempo de Execução e Tratamento de Respostas

* **Interface de Resposta Unificada:** `CafResponse` inclui tipos de resultado estruturados:
  * `sucesso` usando `CafSuccessResponse`
  * `falha` usando `CafFailureResponse`
  * `registro`, `carregamento`, `cancelado`, e `erro` estados
* **Respostas dos Módulos Fortemente Tipadas:**
  * `CafDocumentDetectorResult`
  * `CafFaceLivenessResult`

#### Suporte a Módulos

* Módulos suportados por meio de `CafModuleType` enum:
  * `DOCUMENT_DETECTOR`
  * `DOCUMENT_DETECTOR_UI`
  * `FACE_LIVENESS`
  * `FACE_LIVENESS_UI`

#### Melhorias de Configuração

* **Personalização Flexível da Interface:**
  * Tema de cores via `CafColorConfiguration`
  * Conteúdo personalizado da etapa de confirmação via `CafConfirmationNextStepContentConfiguration`
* **Suporte a Falhas e Logs:**
  * Tipos de falha baseados em enum (`CafFailureType`)
  * Logs estruturados com níveis de log (`CafLogLevel`)

#### Mudanças que quebram compatibilidade

* **Novo Módulo de Integração:** `@caf.io/react-native-sdk` substitui quaisquer implementações isoladas anteriores

### @caf.io/react-native-face-liveness\@4.0.0-beta1

#### Novos recursos

* **Integração Modular do SDK:** O módulo Face Liveness agora está disponível como um pacote independente para uso modular dentro da nova `@caf.io/react-native-sdk` arquitetura.
* **Novo Hook: `useCafFaceLiveness`:** Apresenta um hook React prático para aplicar e acionar fluxos de face liveness com suporte a configuração.
* **API de Execução Direta:** O hook expõe `applyCafFaceLiveness()` para acionar o fluxo usando a configuração mais recente.

#### Melhorias de Configuração

* **Configuração Tipada via `CafFaceLivenessConfiguration`:**
  * Objeto centralizado para configurar a experiência de liveness
  * Suporta `CafFaceLivenessBuilderConfiguration` aninhado para controle avançado
* **As Opções do Builder Incluem:**
  * `authBaseUrl` e `livenessBaseUrl` para proxy e endpoints personalizados
  * `certificates[]` para pinagem TLS
  * `screenCaptureEnabled` alternar
  * `debugModeEnabled` para logs verbosos e ferramentas de desenvolvedor
  * Suporte à tela de carregamento via `carregamento`

#### Mudanças que quebram compatibilidade

* **Hook e Fluxo Legados Removidos:**
  * `useFaceLiveness` foi removido e substituído pelo novo `useCafFaceLiveness` hook.
  * `startFaceLiveness()` não é mais necessário; o fluxo agora é acionado por meio de `applyCafFaceLiveness()` dentro do hook.
* **Objeto de Configuração Renomeado e Simplificado:**
  * `FaceLivenessSettings` ➜ substituído por `CafFaceLivenessConfiguration`, que contém um `CafFaceLivenessBuilderConfiguration` aninhado para melhor estrutura e segurança de tipos.
* **Remoções de Enums e Substituições de Tipos:**
  * Os seguintes enums foram removidos:
    * `Stage` ➜ não é mais necessário não é mais necessário `Filter`, `Time` ➜ não é mais necessário; o comportamento agora é tratado pela estrutura de configuração
    * `Erro` ➜ substituído por `erro` e `falha` estruturas padrão
  * A formatação condicional relacionada e as transformações de enums específicas por plataforma foram eliminadas.
* **Formato de Resposta Simplificado:**
  * `FaceLivenessResponse`, `FaceLivenessResult`, `FaceLivenessError`, e `FaceLivenessFailure` ➜ todos removidos

### @caf.io/react-native-face-liveness-ui\@1.0.0-beta1

#### Novos recursos

* **Integração Modular de UI:**\
  O módulo Face Liveness UI agora está disponível como um pacote independente, projetado para funcionar de forma autônoma ou como parte do novo `@caf.io/react-native-sdk` arquitetura.
* **Novo Hook: `useCafFaceLivenessUI`:**\
  Fornece um hook React prático para aplicar e acionar o fluxo de UI de face liveness com suporte a configurações personalizadas.
* **API de Execução Direta:**\
  O hook expõe `applyCafFaceLivenessUI()` para inicializar o fluxo de UI nativo usando a configuração atual.

#### Melhorias de Configuração

* **Configuração Tipada via `CafFaceLivenessUIConfiguration`:**\
  Um objeto centralizado para gerenciar tanto os aspectos funcionais quanto de UI da experiência de liveness.
* **As Opções do Builder Incluem:**
  * `authBaseUrl` e `livenessBaseUrl` para endpoints de serviço personalizados
  * `certificates[]` para comunicação TLS segura
  * `screenCaptureEnabled` e `debugModeEnabled` flags
  * Controle do indicador de carregamento por meio da `carregamento` flag
* **Personalização da Tela de Instruções via `instructionScreenConfiguration`:**
  * Suporte para imagem instrucional, título, descrição e mensagens de etapas ordenadas
  * Rótulo de botão personalizável para orientar os usuários no fluxo

### @caf.io/react-native-document-detector\@4.0.0-beta1

#### Novos recursos

* **Integração Modular do SDK:**\
  O módulo Document Detector agora está disponível como um pacote independente para uso modular dentro do `@caf.io/react-native-sdk` arquitetura.
* **Novo Hook: `useCafDocumentDetector`:**\
  Hook React que permite inicializar o fluxo de detecção de documentos serializando e aplicando a configuração por meio de `applyCafDocumentDetector()`.

#### Melhorias de Configuração

* **Configuração Tipada via `CafDocumentDetectorConfiguration`:**\
  Configuração centralizada e com segurança de tipos usando a `CafDocumentDetectorBuilderConfiguration` interface.
* **Composição Avançada de Fluxo com `flow`:**\
  Defina a sequência de captura usando `CafDocumentDetectorFlow[]`, com suporte a vários documentos como `RG`, `CNH`, `Passaporte`, e mais.
* **Configuração Expandida de Upload:**
  * Controle os formatos permitidos (`PNG`, `JPG`, `PDF`, `HEIC`, etc.)
  * Compressão de arquivos e limites de tamanho
  * Suporte completo a proxy com opções de autenticação
* **Personalização de UI e Comportamento:**
  * Texto e layout personalizados da tela de pré-visualização
  * Mensagens e recursos de upload de documentos
  * Orientação passo a passo e rótulos de instrução
  * Configurações de tempo limite, captura manual, pop-up e segurança
* **Suporte à Personalização de Mensagens:**\
  Ajuste fino do feedback ao usuário durante o processo de captura com `CafDocumentDetectorMessageCustomization`.
* **Recursos de Segurança:**\
  Configure flags de desenvolvimento (`useDevelopmentMode`, `useAdb`, `useDebug`) para ambientes de teste controlados.
* **Restrições de País para Passaportes:**\
  Restrinja os documentos de passaporte aceitos usando `allowedPassportCountryList` com base nos códigos ISO 3166-1 alfa-3.

#### Mudanças que quebram compatibilidade

* **Hook e Fluxo Legados Removidos:**
  * `useDocumentDetector` foi removido e substituído pelo novo `useCafDocumentDetector` hook.
  * `startDocumentDetector()` não é mais necessário; a execução do fluxo agora ocorre por meio de `applyCafDocumentDetector()` dentro do hook.
* **Objeto de Configuração Renomeado e Reestruturado:**
  * `DocumentDetectorSettings` ➜ substituído por `CafDocumentDetectorConfiguration`, que envolve um `CafDocumentDetectorBuilderConfiguration`.
* **Configuração de Etapa:**
  * `DocumentDetectorStep[]` ➜ substituído por `CafDocumentDetectorFlow[]` para definir etapas de captura de documentos.
* **Personalização de Mensagens:**
  * `DocumentDetectorMessageSettings` ➜ substituído por `CafDocumentDetectorMessageCustomization`.
* **Configurações de Pré-visualização:**
  * `DocumentDetectorPreviewSettings` ➜ substituído por `CafDocumentDetectorPreviewCustomization`.
* **Configurações de Upload:**
  * `DocumentDetectorUploadSettings` ➜ renomeado para `CafDocumentDetectorUploadSettings`.
* **Configurações de Proxy:**
  * `DocumentDetectorProxySettings` ➜ substituído por `CafDocumentDetectorProxySettings` com estrutura equivalente, mas novo tipo.
* **Configurações de Segurança:**
  * `DocumentDetectorSecuritySettings` ➜ substituído por `CafDocumentDetectorSecuritySettings`.
* **Configuração do Sensor:**
  * `DocumentDetectorSensorSettings` ➜ não existe mais como um objeto independente.
* **Restrição de País:**
  * `allowedPassportList` usado `enum CountryCodes` ➜ agora usa `CafCountryCodes`.
* **Reestruturação de Enums:**
  * Enums como `Stage`, `Resolution`, `CaptureMode`, e `Erro` foram removidos. Seu comportamento foi substituído por propriedades estruturadas dentro dos objetos de configuração ou removido completamente para simplificação.
* **Formato de Resposta Simplificado:**
  * `DocumentDetectorResponse`, `DocumentDetectorResult`, e `DocumentDetectorError` ➜ não é mais usado. O módulo agora retorna seu sucesso/falha por meio do fluxo de resposta centralizado dentro do SDK ou é tratado diretamente pelo feedback da integração nativa.

### @caf.io/react-native-document-detector-ui\@1.0.0-beta1

#### Novos recursos

* **Integração Modular de UI:**\
  O módulo Document Detector UI agora está disponível como um pacote independente, projetado para funcionar de forma autônoma ou como parte do novo `@caf.io/react-native-sdk` arquitetura.
* **Novo Hook: `useCafDocumentDetectorUI`:**\
  Fornece um hook React para aplicar e acionar o fluxo de UI de detecção de documentos com uma interface limpa e declarativa.
* **API de Execução Direta:**\
  O hook expõe `applyCafDocumentDetectorUI()` para inicializar o fluxo de UI nativo do detector de documentos usando a configuração mais recente.

#### Melhorias de Configuração

* **Configuração Tipada via `CafDocumentDetectorUIConfiguration`:**\
  Configuração centralizada que combina o fluxo principal, telas de instrução e etapas de seleção de documentos.
* **As Opções do Builder Incluem:**
  * `flow` configuração com `CafDocumentDetectorFlow[]` para definir etapas de captura de documentos
  * Controle de upload por meio de `uploadSettings`, incluindo opções de tamanho de arquivo, compressão e formato
  * Configuração de proxy com autenticação opcional via `proxySettings`
  * Flags de segurança para depuração e testes por meio de `securitySettings`
  * Alternâncias de captura manual, controle da tela de pré-visualização e personalização de tempo limite
* **Personalização da Tela de Instruções via `instructionScreenConfiguration`:**
  * Defina imagens, títulos, rótulos de botão e mensagens de instrução para as fases de captura e upload
  * Melhore a orientação ao usuário com visuais e descrições detalhadas passo a passo
* **Interface de Seleção de Documento via `documentSelectionScreenConfiguration`:**
  * Tela opcional que permite aos usuários escolher o tipo de documento antes de a captura começar
  * Título e descrição personalizáveis para combinar com o tom do seu app e o fluxo do usuário

### @caf.io/react-native-sdk\@1.0.0-beta1

#### Novos recursos

* **Apresentando `@caf.io/react-native-sdk`:** Um SDK unificado para integrar os módulos Face Liveness e Document Detector em aplicações React Native
* **Suporte ao Padrão Builder:** Configuração simplificada usando `CafSdkBuilderConfiguration`, permitindo configuração com segurança de tipos e composição modular
* **Modelo de Configuração Unificado:** Gerencie a ordem de execução (`presentationOrder`), a temática da interface (`CafColorConfiguration`), e o comportamento do fluxo de forma centralizada
* **Tratamento Consistente dos Módulos:** Autenticação compartilhada, ambiente (`CafEnvironment`), logs (`CafLog`), e estrutura de resposta em todos os módulos
* **Integração Simplificada:** Hook React para inicializar e gerenciar todo o ciclo de vida do SDK
* **Rastreamento de Estado em Tempo Real:** Fornece um `response` objeto unificado com atualizações em tempo real sobre carregamento, cancelamento, sucesso, falha e logs
* **Acionamento Manual:** Expõe `initialize()` para iniciar o fluxo após a configuração nativa ser concluída
* **Gerenciamento de Eventos Integrado:** Escuta e reage a todas as emissões de `CafUnifiedEvent` , abstraindo a camada de comunicação nativa

#### Tempo de Execução e Tratamento de Respostas

* **Interface de Resposta Unificada:** `CafResponse` inclui tipos de resultado estruturados:
  * `sucesso` usando `CafSuccessResponse`
  * `falha` usando `CafFailureResponse`
  * `registro`, `carregamento`, `cancelado`, e `erro` estados
* **Respostas dos Módulos Fortemente Tipadas:**
  * `CafDocumentDetectorResult`
  * `CafFaceLivenessResult`

#### Suporte a Módulos

* Módulos suportados por meio de `CafModuleType` enum:
  * `DOCUMENT_DETECTOR`
  * `DOCUMENT_DETECTOR_UI`
  * `FACE_LIVENESS`
  * `FACE_LIVENESS_UI`

#### Melhorias de Configuração

* **Personalização Flexível da Interface:**
  * Tema de cores via `CafColorConfiguration`
  * Conteúdo personalizado da etapa de confirmação via `CafConfirmationNextStepContentConfiguration`
* **Suporte a Falhas e Logs:**
  * Tipos de falha baseados em enum (`CafFailureType`)
  * Logs estruturados com níveis de log (`CafLogLevel`)

#### Mudanças que quebram compatibilidade

* **Novo Módulo de Integração:** `@caf.io/react-native-sdk` substitui quaisquer implementações isoladas anteriores


---

# 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/react-native/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.