> 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/installation-guide.md).

# Guia de Instalação

Instale e configure o Certta para React Native. Aprenda sobre os requisitos do SDK, seleção de módulo, permissões, configuração de sessão, atualizações de token em tempo de execução e temas de cores.

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

## Instalando o SDK para React Native

Este guia orienta você pela configuração necessária para baixar, configurar e inicializar **Certta** (`@caf.io/react-native-sdk` 5.4.0+) em um aplicativo React Native.

### Requisitos

#### 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

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

A versão do pacote publicada é **5.4.0**. Importe os hooks do Certta DevX do pacote principal:

```typescript
import {
  useCerttaSdk,
  useCafFaceLiveness,
  useCafDocumentDetector,
  useCafDocumentDetectorUI,
  CafEnvironment,
} from '@caf.io/react-native-sdk';
```

{% hint style="info" %}
A versão sequencial `useCafSdk` A API continua disponível no mesmo pacote. Prefira o Certta DevX para novas integrações. Veja [Migrando do CafSdk](/caf-sdk/caf-sdk-pt-br/react-native/migrating-from-cafsdk.md).
{% endhint %}

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

{% tabs %}
{% tab title="Expo" %}
Ao usar o Expo, `caf-modules-config.json` é gerado a partir de `app.json`. Adicione o plugin:

```json
{
  "plugins": [
    [
      "@caf.io/react-native-sdk",
      {
        "documentDetector": true,
        "faceLiveness": true,
        "documentDetectorUI": true,
        "faceLivenessUI": true,
        "livenessProviders": ["iproov-lite", "payface"],
        "fingerprint": true
      }
    ]
  ]
}
```

{% endtab %}

{% tab title="CLI da comunidade" %}
Crie `caf-modules-config.json` na raiz do seu app:

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

{% endtab %}
{% endtabs %}

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

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

**iProov e Protobuf**

* **`iproov-lite`**: use quando seu app tiver como alvo **Protobuf JavaLite** — a escolha usual para um binário Android menor.
* **`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 (`fingerprint`, booleano). O padrão é `false`. A impressão digital é coletada como parte do fluxo de vivacidade, então ela só é incluída quando `faceLiveness` ou `faceLivenessUI` também está habilitado.

Entre em contato com o Suporte CAF para solicitar a ativação no backend. Se isso não estiver habilitado do nosso lado, o SDK não acionará a biblioteca de fingerprint mesmo que a propriedade esteja `true` localmente.

### Etapa 3: configuração do Android

Configure o `bloco repositories` no arquivo `android/build.gradle.kts` (normalmente na raiz):

{% tabs %}
{% tab title="Script Kotlin" %}

```kotlin
repositories {
    // Repositório Caf
    maven { url = uri("https://repo.combateafraude.com/android/release") }
}
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
repositories {
    // Repositório Caf
    maven { url "https://repo.combateafraude.com/android/release" }
}
```

{% endtab %}
{% endtabs %}

### Etapa 4: 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 possa vincular os módulos nativos.
* Execute novamente `pod install` sempre que dependências nativas forem adicionadas ou atualizadas.

***

## Permissões

### Android

Declare o seguinte em **AndroidManifest.xml**:

**Face Liveness**

| Permissão                     | Descrição                                                           | Necessidade |
| ----------------------------- | ------------------------------------------------------------------- | ----------- |
| `android.permission.CAMERA`   | Acesso à câmera para verificação facial (liveness).                 | Obrigatório |
| `android.permission.INTERNET` | Comunicação com serviços de autenticação e verificação (HTTPS/WSS). | Obrigatório |

**Document Detector**

| Permissão                                  | Descrição                                                                  | Necessidade          |
| ------------------------------------------ | -------------------------------------------------------------------------- | -------------------- |
| `android.permission.CAMERA`                | Acesso à câmera para capturar imagens de documentos.                       | Somente para captura |
| `android.permission.INTERNET`              | Enviar imagens capturadas para processamento e validação.                  | Obrigatório          |
| `android.permission.READ_EXTERNAL_STORAGE` | Acessar arquivos armazenados quando o envio de documentos estiver ativado. | Somente para upload  |

### iOS

Declare o seguinte em **Info.plist**:

**Face Liveness**

| Permissão                  | Descrição                                                           | Necessidade |
| -------------------------- | ------------------------------------------------------------------- | ----------- |
| `NSCameraUsageDescription` | Acesso à câmera para verificação facial (liveness).                 | Obrigatório |
| Acesso à rede              | Comunicação com serviços de autenticação e verificação (HTTPS/WSS). | Obrigatório |

**Document Detector**

| Permissão                        | Descrição                                                                  | Necessidade          |
| -------------------------------- | -------------------------------------------------------------------------- | -------------------- |
| `NSCameraUsageDescription`       | Acesso à câmera para capturar imagens de documentos.                       | Somente para captura |
| Acesso à rede                    | Enviar imagens capturadas para processamento e validação.                  | Obrigatório          |
| `NSPhotoLibraryUsageDescription` | Acessar arquivos armazenados quando o envio de documentos estiver ativado. | Somente para upload  |

***

## Configurando a sessão

Para gerar seu token móvel, siga este guia:

{% content-ref url="/pages/350b53d9674174220c34ca357260b91ef975ad64" %}
[Autenticação](/caf-sdk/caf-sdk-pt-br/authentication.md)
{% endcontent-ref %}

Inicialize o Certta assim que tiver um token móvel válido (JWT) e o ID do usuário — normalmente após o login:

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

function App() {
  const { configureSDK, isInitialized } = useCerttaSdk();

  useEffect(() => {
    void (async () => {
      try {
        await configureSDK({
          mobileToken: 'seu-jwt',
          userId: 'id-do-usuario',
          environment: CafEnvironment.PROD,
          securityEnabled: true,
        });
      } catch {
        // Trate BRIDGE_EXCEPTION
      }
    })();
  }, []);

  // aguarde isInitialized() quando necessário
}
```

#### `CerttaConfiguration` parâmetros

| Parâmetro            | Tipo                     | Descrição                                                            |
| -------------------- | ------------------------ | -------------------------------------------------------------------- |
| `mobileToken`        | `string`                 | JWT móvel da CAF do seu backend.                                     |
| `userId`             | `string`                 | Identificador do usuário final.                                      |
| `environment`        | `CafEnvironment`         | Ambiente de backend: `PROD`, `BETA`, ou `DEV`.                       |
| `securityEnabled`    | `boolean`                | Ativa verificações de segurança. Padrão `true`.                      |
| `colorConfiguration` | `CafColorConfiguration?` | Tema de cores opcional. Veja [Tematização de cores](#color-theming). |

{% hint style="info" %}
`configureSDK` rejeita com `CerttaPlatformException` e código `BRIDGE_EXCEPTION` quando o mapeador nativo rejeita a configuração.
{% endhint %}

### Atualizações de configuração em tempo de execução

`userId` e `mobileToken` podem ser atualizados após a configuração inicial `configureSDK` sem repetir a configuração completa:

```typescript
const { updateUserId, updateMobileToken } = useCerttaSdk();

updateUserId('new-user-id');
updateMobileToken('new-jwt-token');
```

{% hint style="warning" %}
Use esses métodos sempre que seu app fizer logout/login ou quando seu backend emitir um JWT atualizado, para que o Certta permaneça sincronizado com a sessão ativa.
{% endhint %}

### Logs

Os logs do pipeline do SDK são coletados por `useCerttaSdk` no `logs` array:

```typescript
const { logs } = useCerttaSdk();

useEffect(() => {
  logs.forEach((log) => {
    console.log(`${log.level}: ${log.message}`);
  });
}, [logs]);
```

***

## Tematização de cores

Face Liveness e Document Detector oferecem suporte a cores personalizadas para que a interface do SDK possa combinar com a sua marca. Passe strings hexadecimais (por exemplo `"#RRGGBB"`) em `CafColorConfiguration` ao chamar `configureSDK`:

```typescript
await configureSDK({
  mobileToken: 'seu-jwt',
  userId: 'id-do-usuario',
  environment: CafEnvironment.PROD,
  colorConfiguration: {
    primaryColor: '#FF0000',
    secondaryColor: '#00FF00',
    backgroundColor: '#FFFFFF',
    contentColor: '#000000',
    mediumColor: '#D1D1D1',
    dialogBackgroundColor: '#FFFFFF',
    dialogBorderColor: '#0C395E',
  },
});
```

{% hint style="info" %}
Todos os campos de cor são opcionais. Substitua apenas as cores de que você precisa.
{% endhint %}

| Propriedade de cor      | Descrição                                           |
| ----------------------- | --------------------------------------------------- |
| `primaryColor`          | Cor principal para botões e destaques.              |
| `secondaryColor`        | Cor secundária para elementos complementares.       |
| `backgroundColor`       | Cor de fundo da tela.                               |
| `contentColor`          | Cor usada para textos e ícones.                     |
| `mediumColor`           | Cor neutra para elementos como barras de progresso. |
| `dialogBackgroundColor` | Cor de fundo de diálogos e pop-ups.                 |
| `dialogBorderColor`     | Cor da borda de diálogos e pop-ups.                 |

***

## Ofuscação de código

Adicione regras ProGuard/R8 ao `android/app/proguard-rules.pro` para que o SDK continue funcionando após a ofuscação. Veja o conjunto completo de regras em [Legacy Getting Started — Regras ProGuard/R8](/caf-sdk/caf-sdk-pt-br/react-native/getting-started-with-the-sdk.md#proguardr8-rules).

***

## Próximos passos

{% content-ref url="/pages/a6456da207c8b8aed6bee17b024cf67619d1364d" %}
[Face Liveness](/caf-sdk/caf-sdk-pt-br/react-native/face-liveness.md)
{% endcontent-ref %}

{% content-ref url="/pages/1e1279259ffc8e30bf8c30a7c687900fe4ab864f" %}
[Document Detector](/caf-sdk/caf-sdk-pt-br/react-native/document-detector.md)
{% endcontent-ref %}


---

# 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/installation-guide.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.