> 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).

# Introdução legada com o SDK

{% hint style="warning" %}
**Certta DevX** é o caminho de integração recomendado a partir de **@caf.io/react-native-sdk 5.4.0** (configure a sessão uma vez, abra os módulos independentemente com hooks dedicados). Para o sequencial `useCafSdk` API, continue usando este guia. Para adotar o DevX, consulte o [Guia de Instalação](/caf-sdk/caf-sdk-pt-br/react-native/installation-guide.md) e [Migrando do CafSdk](/caf-sdk/caf-sdk-pt-br/react-native/migrating-from-cafsdk.md).
{% endhint %}

## Sobre o CafSDK

Esta documentação técnica cobre 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 múltiplos 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 spoofing.

**Características técnicas:**

* Configuração de URL para autenticação (`authBaseUrl`) e verificação de liveness (`livenessBaseUrl`)
* Suporte à configuração de proxy reverso com pinagem de certificado
* Flags para habilitar captura de tela e modo de depuração
* Tentativas de repetição configuráveis e execução de 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, carteira de identidade, cartão de CPF, 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 envio do arquivo do documento
* Opções avançadas de personalização para UI, mensagens e comportamento

***

## Instalação

### Requisitos

Para usar os módulos do CafSDK no React Native, verifique se seu projeto atende 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 |
| --------------------------------- | ------ |
| **Destino de implantação do iOS** | 15.0   |
| **Xcode**                         | 26.0   |
| **Swift**                         | 5.10   |
|                                   |        |

### Etapa 1: Instale o SDK

Instale o pacote principal do SDK:

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

### Etapa 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 de `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 sã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`** é definido como o provedor padrão de Face Liveness.
{% endhint %}

Defina cada sinalizador do 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 iProov.

{% hint style="warning" %}
Se você incluir o **PayFace** provedor, você também deve usar **iProov Lite** (`iproov-lite`). O PayFace é compilado com Protobuf JavaLite; combiná-lo com **`iproov-full`** gera 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 (booleano). 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 liveness, então só é incluído quando `faceLiveness` ou `faceLivenessUI` também está habilitado. Definir `"fingerprint": true` sem um módulo de liveness habilitado não tem efeito.

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

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

Acesse o `diretório ios/` diretório do seu projeto React Native e execute:

```sh
pod install
```

* Esta etapa é obrigatória para que o iOS vincule corretamente os módulos nativos e suas dependências necessárias.
* Sempre 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 em 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 (liveness). | Obrigatório |
| `android.permission.INTERNET` | Permite comunicação com serviços de autenticação e verificação (HTTPS/WSS).               | Obrigatório |

**Para Document Detector**

| Permissão                                  | Descrição                                                                                       | Necessidade          |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------------------- |
| `android.permission.CAMERA`                | Permite acesso à câmera para capturar imagens de documentos.                                    | Somente para captura |
| `android.permission.INTERNET`              | Permite que as imagens capturadas sejam enviadas aos servidores para processamento e validação. | Obrigatório          |
| `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 em 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 (liveness). | Obrigatório |
| `Acesso à rede`            | Permite comunicação com serviços de autenticação e verificação (HTTPS/WSS).               | Obrigatório |

**Para Document Detector:**

| Permissão                        | Descrição                                                                                       | Necessidade          |
| -------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------- |
| `NSCameraUsageDescription`       | Permite acesso à câmera para capturar imagens de documentos.                                    | Somente para captura |
| `Acesso à rede`                  | Permite que as imagens capturadas sejam enviadas aos servidores para processamento e validação. | Obrigatório          |
| `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 nenhuma configuração adicional.

#### iOS

De acordo com a documentação da Apple, a configuração de `Localizações` e `CFBundleLocalizations` deve ser feita 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

A `useCafSdk` hook serve como o 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 as 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 contendo manipuladores de eventos para a execução do SDK (sucesso, erro, carregamento etc.).
* **`initialized`**: Estado booleano indicando 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();

// Inicializa 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 () => {
    // Aplica a configuração dos módulos
    // Todas as funções apply 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 de autenticação
      livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para verificação de liveness
      certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
      screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
      debugModeEnabled: true,                                         // Ativa logs de depuração
      executeFaceAuth: false,                                         // Ativa a autenticação facial
      maxRetryAttempts: 2,                                            // Máximo de tentativas de повтор
    });
    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 da sessão (opcional)**

A `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ê tiver a oportunidade de pré-carregar a sessão antes de o usuário realmente precisar 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();

// Inicializa o SDK (monta 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 () => {
    // Aplica a configuração dos módulos
    // Todas as funções apply 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 de autenticação
      livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para verificação de liveness
      certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
      screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
      debugModeEnabled: true,                                         // Ativa logs de depuração
      executeFaceAuth: false,                                         // Ativa a autenticação facial
      maxRetryAttempts: 2,                                            // Máximo de tentativas de повтор
    });
    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é-carrega a sessão (opcional)
loadSession();

// Depois, 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();

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

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

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

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

// Aplica 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

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

* **log**: Captura mensagens de log com diferentes níveis (DEBUG, USAGE, INFO)
* **loading**: Indica o início do processamento do módulo
* **success**: Após a conclusão bem-sucedida, cada módulo dispara um evento contendo um `CafSuccessResponse[]` objeto
* **error**: Se ocorrer um problema durante a execução, este evento é disparado com a mensagem de erro
* **failure**: Indica uma falha de Face Liveness, fornecendo detalhes sobre o tipo de falha
* **cancelled**: 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 suportadas       |
| `NETWORK_EXCEPTION`                | Problemas de conectividade de rede                 |
| `SERVER_EXCEPTION`                 | Falha no processamento do backend                  |
| `TOKEN_EXCEPTION`                  | Token inválido/expirado                            |
| `CAPTURE_ALREADY_ACTIVE_EXCEPTION` | Sessão de captura concorrente                      |
| `UNEXPECTED_ERROR_EXCEPTION`       | Erro crítico irrecuperável                         |
| `USER_TIMEOUT_EXCEPTION`           | Tempo limite de captura excedido                   |
| `IMAGE_NOT_FOUND_EXCEPTION`        | Dados de 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ções 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 de proxy                      |
| `SECURITY_EXCEPTION`               | Erro de validação de segurança                     |
| `BRIDGE_EXCEPTION`                 | erro de comunicação na 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` | 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 ruins    |  ❌  |  ✅  |
|      `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 fica a foto                                                                                      |
| `RG_BACK`    | Verso do documento RG                                                                                                         |
| `RG_FULL`    | Documento RG aberto, exibindo juntos a frente e o verso                                                                       |
| `CNH_FRONT`  | Frente do documento CNH, onde fica a foto                                                                                     |
| `CNH_BACK`   | Verso do documento CNH                                                                                                        |
| `CNH_FULL`   | Documento CNH aberto, exibindo juntos a frente e o verso                                                                      |
| `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 fica a foto                                                                                    |
| `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();

// Aplica 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 do recurso local
    title: "Título personalizado",
    description: "Siga as etapas abaixo:",
    steps: ["Mantenha o telefone parado", "Garanta boa iluminação"],
    buttonText: "Iniciar a leitura",
  },
});
```

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

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

// Aplica 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 parado",
      "Garanta boa iluminação",
      "Evite reflexos"
    ],
    buttonText: "Iniciar",
  },
  documentSelectionScreen: {
    title: "Selecione o tipo de documento",
    description: "Escolha qual documento você deseja enviar",
  },
});
```

### Configuração de Proxy

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

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

// Aplica 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();

// Aplica a configuração ao inicializar
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  messageCustomization: {
    waitMessage: "Preparando a câmera...",
    fitTheDocumentMessage: "Posicione o documento dentro da moldura",
    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 parado",
              "Garanta boa iluminação",
              "Evite reflexos",
              "Encaixe o documento no enquadramento"
            ],
            buttonText: "Iniciar Captura",
          },
          documentSelectionScreen: {
            title: "Selecionar Tipo de Documento",
            description: "Escolha o documento que você deseja enviar",
          },
        });

        retorna 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 do React Native para o 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 ProGuard/R8 do React Native #############################

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

### Retrofit ##################################################################
# Preserve assinaturas genéricas, classes internas e métodos de encapsulamento para reflexão do Retrofit.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Mantenha anotações visíveis em tempo de execução em métodos e parâmetros.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Mantenha os valores padrão das anotações.
-keepattributes AnnotationDefault
# Retenha os parâmetros dos métodos de serviço para interfaces com anotações do Retrofit.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suprima 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$*
# Mantenha 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>
# Preserve as continuations usadas pelas funções suspend do Kotlin.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# Para o modo completo do R8: mantenha os tipos de retorno genéricos para métodos do Retrofit.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preserve a classe Response do Retrofit.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### END Retrofit ##############################################################

### OkHttp ####################################################################
# Suprima avisos para anotações JSR 305.
-dontwarn javax.annotation.**
# Adapte os nomes de arquivo de recursos para o banco de dados interno de public suffix.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suprima 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.**
# Mantenha 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
### END OkHttp ################################################################

### Kotlin Serialization ######################################################
# Mantenha objetos Companion para classes serializáveis.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Mantenha funções serializer nos objetos companion.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Mantenha 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(...);
}
# Preserve objetos Companion em kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve 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(...);
}
### END Kotlin Serialization #################################################

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

### CAF - Combate a Fraude ############################################## 
# Mantenha atributos de exceções.
-keepattributes Exceptions
# Preserve 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.** { *; }
# Suprima avisos para java.nio.file e certas classes internas do OkHttp.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Mantenha campos em classes que estendem GeneratedMessageLite (para uso do Tink).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preserve classes do TensorFlow.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preserve 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.**
# Suprima avisos para classes concorrentes Flow.
-dontwarn java.util.concurrent.Flow*
# Preserve classes do 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:** Realize 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
* **Trate erros com elegância:** Implemente o tratamento adequado de erros para todos os possíveis cenários de erro e falha
* **Teste com dispositivos diferentes:** Garanta compatibilidade entre diferentes especificações de dispositivos e tamanhos de tela

***

## Problemas conhecidos

### Falha: os fragments da tela nunca devem ser restaurados

#### Descrição

Em aplicativos React Native que consomem SDKs nativos Android, uma falha pode ocorrer quando o sistema operacional recria a Activity principal depois que ela foi destruída em segundo plano. A mensagem de erro típica exibida é:

```
java.lang.IllegalStateException: os fragments da 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 fragments da 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() {

  //...código

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

  //...código
}
```

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

#### Impacto

Essa alteração permite que o aplicativo lide com cenários de recriação da Activity de forma elegante, sem travar, mantendo uma experiência de usuário fluida 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 oferecer suporte ao Android 16 (`compileSdk` / `targetSdk` 36), alinhando-se aos requisitos do Google Play para apps direcionados às versões recentes do Android.

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

**Face Liveness:** Corrigido um problema no fluxo do Payface em que uma validação facial com falha ainda podia ser relatada como sucesso. Agora o SDK trata corretamente as falhas de validação e exibe 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 incorreto de orientação da imagem na prévia, falhas de captura automática com fotos finais desalinhadas e pequenos ajustes de interface 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" %}
**Alteração de breaking :** 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 é 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 precisa estar habilitado no Backoffice. Se não estiver habilitado no Backoffice, o SDK nunca chamará a biblioteca de fingerprint e nenhum dado será enviado, mesmo que a propriedade esteja definida como `true` localmente.
{% endhint %}

#### Destaques

* **Módulo Fingerprint opcional:** Controle a inclusão do recurso de fingerprint diretamente de `caf-modules-config.json`. Ele é desativado por padrão, garantindo que você só inclua a dependência quando for 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

A intermediária `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**

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

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

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

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

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

**Comportamento do estado da resposta**

A `useCafSdk` o ciclo de vida da resposta mudou e pode exigir ajustes se você dependia das redefinições implícitas de estado anteriores:

* `initialize()` agora **redefine** o `response` objeto (`success`, `failure`, `error`, `cancelled`, `log`, `loading`) no início de cada chamada.
* A `Sucesso`, `Falha`, `Erro`, e `Cancelado` eventos agora definem todos `initialized` de volta para `false`.
* A `Carregando` e `Carregado` eventos **não limpam mais** `success` / `failure` / `error` / `cancelled` — eles apenas atualizam o `loading` sinalizador.

#### Recursos

* **Novo tipo de erro `CafErrorType.BRIDGE_EXCEPTION`:** emitido quando a bridge 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 de 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 bridge (nomes de métodos nativos, nomes de eventos como `CafUnifiedEvent.*`, e chaves de payload de resposta como `moduleName` / `signedResponse`) é **inalterado**. O único trabalho de migração está nos **objetos de configuração TypeScript** que você passa para os hooks do módulo.

#### 1. Remova o `configuração` invólucro

Mova cada campo para fora 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 da UI (configuração + campos renomeados)

**UI do Document Detector**

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

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

**UI de 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 o seu app dependia do efeito colateral antigo em que um `Carregando` / `Carregado` evento limpava `success` / `failure` / `error`, 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

* Fortface CDN do Maven não encontrado

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

#### Data de lançamento

* 06-10-2026

#### Correções

* Fortface CDN do Maven não encontrado

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

#### Data de lançamento

* 06-10-2026

#### Correções

* Fortface CDN do Maven não encontrado

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

#### Data de lançamento

* 06-09-2026

#### Atualizações

* **Provedor de Payface Liveness (Android)**: Atualize a versão de `1.18.2` para `1.19.2`.
* **Provedor de Payface Liveness (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" %}
**Alteração de breaking :** 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 no momento da compilação. **PayFace** requer **`iproov-lite`** (Protobuf JavaLite); emparelhar PayFace com **`iproov-full`** causa conflitos de Protobuf durante a compilação. Se omitido, o SDK usa por padrão **`iproov-lite`** em ambas as plataformas. Um **valor vazio ou inválido** causa um erro de compilação em **Android**; em **iOS**, um valor vazio também recorre a `iproov-lite`, mas um valor inválido causa falha na compilação. Veja [Etapa 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` entre `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 iProov Liveness**: Documentação e padrões atualizados para refletir o novo modelo de seleção de provedor.
* **Android ProGuard / R8**: Se o R8 relatar classes ausentes para stubs de lint fornecidos 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 a 4.3.0 farão com que o iProov Liveness se torne inoperante a partir de 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: adicionada nova falha 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.
  * Novo sinalizador 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 activity, incluindo 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 da UI**: Resolvidos problemas de compatibilidade de tema e exceções de transação de fragments 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 document controller para evitar problemas de aplicativo sem resposta.
* **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ções 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 pelo `useCafSdk` hook. Esse 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

**Document Detector / UI do Document Detector**

* **Corrigido travamento ao usar `fluxo` em `CafDocumentDetectorConfig`**: Esse problema fazia com que o SDK fosse fechado 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 "Opções de documento vazias".
* **Corrigido erro ao usar `loadSession` no módulo Document Detector**: Esse problema fazia com que o SDK fosse fechado 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 com antecedência a sessão e a inicialização da câmera, resultando em uma inicialização mais rápida do SDK quando `start()` é chamado. Esse método é opcional e pode ser chamado depois de `initialize()` mas antes de `start()`.
  * `start()`: Inicia o fluxo do SDK depois que a configuração é construída. Esse método inicia a execução sequencial dos módulos configurados.

**Resposta**

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

**Document Detector / UI do Document Detector**

**Android**

* **Modo de captura manual como padrão**: O modo de captura manual desde o início agora é definido como padrão, devido às dificuldades de captura usando o modo automático.
* **Logs de análise**: Adicionados logs de análise detalhados para monitorar os detalhes de captura e 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 é definido como padrão, devido às dificuldades de captura usando o modo automático.

#### Mudanças que quebram compatibilidade

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

#### Correções

**Document Detector / UI do Document Detector**

**Android**

* **Corrigido travamento "A imagem já está fechada"**: Esse problema fazia com que o SDK fosse fechado imediatamente durante a captura de documentos.
* **Corrigido travamento ao usar `fluxo` em `CafDocumentDetectorConfig`**: Esse problema fazia com que o SDK fosse fechado 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 "Opções de documento vazias".
* **Melhoria nas mensagens de erro**: Melhoradas as mensagens de erro para detecção incorreta do tipo de documento, a fim de fornecer feedback mais preciso durante a validação do documento.
* **Fallback no modo de captura**: Melhorado o gerenciamento de estado para transições do modo de captura, a fim de garantir um comportamento consistente e confiável quando os modos de captura manual e automático interagem.
* **Layout**: Melhorada a legibilidade com espaçamento entre linhas maior e margens atualizadas para um layout mais consistente e equilíbrio visual.
* **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 "Ambiente muito escuro", bloqueando a captura até que o sensor detectasse 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**: Melhoradas as mensagens de erro para detecção incorreta do tipo de documento, a fim de fornecer feedback mais preciso durante a validação do documento.
* **Relatório de atestado**: Relato de erros de atestado mais detalhado (rede/token inválido/resposta inválida) com tratamento de erro mais seguro.
* **Identificação de documento**: Corrigido 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 de analytics**: Melhor relato de erros em fluxos de vivacidade facial: distinções mais claras entre rede/servidor, tratamento preciso de permissões da câmera.
* **DocumentDetector**: parou de ativar automaticamente a prévia 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 tipo 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 tipo**: Todos os tipos do TypeScript foram movidos para `@caf.io/react-native-sdk`
  * Remova importações de tipos de 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 sã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 de UI do Document Detector
    * `faceLivenessUI`: Ativar/desativar o módulo de UI do Face Liveness
  * Exemplo de configuração:

    ```json
    {
      "documentDetector": true,
      "faceLiveness": true,
      "documentDetectorUI": false,
      "faceLivenessUI": false
    }
    ```
* **Tratamento unificado de erros**: Tratamento de erros consistente em todos os módulos
* **Desempenho aprimorado**: Tamanho do bundle e desempenho em tempo de execução otimizados por meio da inclusão seletiva de módulos
* **Análises aprimoradas**: Rastreamento de análises unificado em todos os módulos

#### Correções

**iOS**

* **Correção de condição de corrida**: Corrigida a condição de corrida que impedia o SDK de abrir em dispositivos iOS
* **Gerenciamento de memória**: Gerenciamento de memória aprimorado durante as transições entre módulos
* **Problemas de navegação**: Corrigidos problemas de navegação aninhada no iOS

**Android**

* **Gerenciamento de permissões**: Relato de erros de permissão da câmera aprimorado com classificação distinta de erros
* **Estabilidade de rede**: Tratamento de erros de rede e mecanismos de nova tentativa aprimorados
* **Compatibilidade de build**: Configurações de build atualizadas para melhor compatibilidade

**Multiplataforma**

* **Relato de erros**: Clareza das mensagens de erro do servidor aprimorada ao extrair e exibir payloads brutos de erro
* **Estados de carregamento**: Comportamento da tela de carregamento e gerenciamento de estado aprimorados
* **Ciclo de vida do módulo**: Melhor tratamento da inicialização e da limpeza do módulo

#### Guia de migração

Para migrar de pacotes individuais para o SDK unificado:

1. **Remova 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 do módulo**: Crie `caf-modules-config.json` na raiz do seu projeto:

   ```json
   {
     "documentDetector": true,
     "faceLiveness": true,
     "documentDetectorUI": false,
     "faceLivenessUI": false
   }
   ```
4. **Atualize os imports**:

   ```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**: O código da sua implementação existente não precisa mudar. Os hooks e seu uso permanecem 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 de diálogos

### @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 `ativar` 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 controle mais granular da 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 aplicativos React Native
* **Suporte ao padrão Builder:** Configuração simplificada usando `CafSdkBuilderConfiguration`, permitindo configuração com segurança de tipo e composição modular
* **Modelo de configuração unificado:** Gerencie a ordem de execução (`presentationOrder`), tema da UI (`CafColorConfiguration`), e o comportamento do fluxo de forma centralizada
* **Tratamento consistente de módulos:** Autenticação compartilhada, ambiente (`CafEnvironment`), registro de logs (`CafLog`), e estrutura de resposta em todos os módulos
* **Integração simplificada:** Hook do 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 `CafUnifiedEvent` emissões, abstraindo a camada de comunicação nativa

#### Tratamento de execução e resposta

* **Interface de resposta unificada:** `CafResponse` inclui tipos de resultado estruturados:
  * `success` usando `CafSuccessResponse`
  * `failure` usando `CafFailureResponse`
  * `log`, `loading`, `cancelled`, e `error` estados
* **Respostas dos módulos com tipagem forte:**
  * `CafDocumentDetectorResult`
  * `CafFaceLivenessResult`

#### Suporte a módulos

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

#### Melhorias de configuração

* **Personalização flexível da UI:**
  * 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 conveniente do React 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 por meio de `CafFaceLivenessConfiguration`:**
  * Objeto centralizado para configurar a experiência de liveness
  * Suporta aninhados `CafFaceLivenessBuilderConfiguration` para controle avançado
* **As opções do Builder incluem:**
  * `authBaseUrl` e `livenessBaseUrl` para proxy e endpoints personalizados
  * `certificates[]` para fixação de TLS
  * `screenCaptureEnabled` alternar
  * `debugModeEnabled` para logs detalhados e ferramentas de desenvolvedor
  * Suporte à tela de carregamento via `loading`

#### 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 `applyCafFaceLiveness()` dentro do hook.
* **Objeto de configuração renomeado e simplificado:**
  * `FaceLivenessSettings` ➜ substituído por `CafFaceLivenessConfiguration`, que contém um `CafFaceLivenessBuilderConfiguration` para melhor estrutura e segurança de tipo.
* **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 padrão `error` e `failure` estruturas
  * A formatação condicional relacionada e as transformações de enum específicas de 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 da UI:**\
  O módulo Face Liveness UI agora está disponível como um pacote independente, projetado para funcionar de forma independente ou como parte da nova `@caf.io/react-native-sdk` arquitetura.
* **Novo hook: `useCafFaceLivenessUI`:**\
  Fornece um hook conveniente do React para aplicar e acionar o fluxo de UI do face liveness com suporte a configurações personalizadas.
* **API de execução direta:**\
  O hook expõe `applyCafFaceLivenessUI()` para inicializar o fluxo nativo da UI usando a configuração atual.

#### Melhorias de configuração

* **Configuração tipada por meio de `CafFaceLivenessUIConfiguration`:**\
  Um objeto centralizado para gerenciar tanto os aspectos funcionais quanto os 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` sinalizadores
  * controle do indicador de carregamento via o `loading` sinalizador
* **Personalização da tela de instruções via `instructionScreenConfiguration`:**
  * Suporte a uma imagem instrutiva, título, descrição e mensagens de etapas ordenadas
  * Rótulo de botão personalizável para guiar 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 do 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 por meio de `CafDocumentDetectorConfiguration`:**\
  Configuração centralizada e com segurança de tipo usando a `CafDocumentDetectorBuilderConfiguration` interface.
* **Composição avançada de fluxo com `fluxo`:**\
  Defina a sequência de captura usando `CafDocumentDetectorFlow[]`, suportando vários documentos como `RG`, `CNH`, `Passaporte`, e outros.
* **Configuração de upload expandida:**
  * 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 da UI e do comportamento:**
  * Texto e layout personalizados da tela de pré-visualização
  * Mensagens e ativos de upload de documentos
  * Orientação passo a passo e rótulos de instrução
  * Configurações de timeout, captura manual, popup e segurança
* **Suporte à personalização de mensagens:**\
  Ajuste o feedback do usuário durante o processo de captura com `CafDocumentDetectorMessageCustomization`.
* **Recursos de segurança:**\
  Configure sinalizadores 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 alpha-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 encapsula um `CafDocumentDetectorBuilderConfiguration`.
* **Configuração de etapas:**
  * `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 de sensor:**
  * `DocumentDetectorSensorSettings` ➜ não está mais presente como um objeto independente.
* **Restrição de país:**
  * `allowedPassportList` usado `CountryCodes` enum ➜ 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 da UI:**\
  O módulo Document Detector UI agora está disponível como um pacote independente, projetado para funcionar de forma independente ou como parte da nova `@caf.io/react-native-sdk` arquitetura.
* **Novo hook: `useCafDocumentDetectorUI`:**\
  Fornece um hook do 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 nativo de UI do document detector usando a configuração mais recente.

#### Melhorias de configuração

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

### @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 aplicativos React Native
* **Suporte ao padrão Builder:** Configuração simplificada usando `CafSdkBuilderConfiguration`, permitindo configuração com segurança de tipo e composição modular
* **Modelo de configuração unificado:** Gerencie a ordem de execução (`presentationOrder`), tema da UI (`CafColorConfiguration`), e o comportamento do fluxo de forma centralizada
* **Tratamento consistente de módulos:** Autenticação compartilhada, ambiente (`CafEnvironment`), registro de logs (`CafLog`), e estrutura de resposta em todos os módulos
* **Integração simplificada:** Hook do 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 `CafUnifiedEvent` emissões, abstraindo a camada de comunicação nativa

#### Tratamento de execução e resposta

* **Interface de resposta unificada:** `CafResponse` inclui tipos de resultado estruturados:
  * `success` usando `CafSuccessResponse`
  * `failure` usando `CafFailureResponse`
  * `log`, `loading`, `cancelled`, e `error` estados
* **Respostas dos módulos com tipagem forte:**
  * `CafDocumentDetectorResult`
  * `CafFaceLivenessResult`

#### Suporte a módulos

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

#### Melhorias de configuração

* **Personalização flexível da UI:**
  * 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.