> 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 |
| ---------------------------------------------------------- | ------ |
| **API do Android SDK - versão mínima (minSdk)**            | 26     |
| **API do Android SDK - versão de compilação (compileSdk)** | 36     |
| **Kotlin**                                                 | 1.9.10 |
| **Gradle**                                                 | 8.4    |
| **Plugin do Android Gradle (AGP)**                         | 8.3.2  |

#### iOS

| Requisito                        | Versão |
| -------------------------------- | ------ |
| **Target 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 publicada do pacote é **5.4.0**. Importe os hooks do Certta DevX do pacote principal:

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

{% hint style="info" %}
O fluxo sequencial `useCafSdk` A API continua disponível no mesmo pacote. Prefira o Certta DevX para novas integrações. Veja [Migrando do CafSdk](https://docs.caf.io/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",
      {
        "modules": {
          "documentDetector": true,
          "faceLiveness": true,
          "documentDetectorUI": true,
          "faceLivenessUI": true,
          "smartCapture": {
            "enabled": true,
            "autoCapture": true
          }
        },
        "livenessProviders": ["iproov-lite", "payface", "facetec"],
        "fingerprint": true
      }
    ]
  ]
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

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

Defina cada sinalizador de 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) juntamente 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; misturá-lo com **`iproov-full`** causa conflitos de dependência do Protobuf no momento da compilação.
{% endhint %}

**Impressão digital**

O módulo Fingerprint é opcional (`fingerprint`, boolean). O padrão é `false`. A impressão digital é coletada como parte do fluxo de liveness, então só é incluída quando `faceLiveness` ou `faceLivenessUI` também está ativado.

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

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

Configure o `repositórios` bloco no `android/build.gradle.kts` (geralmente na raiz):

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

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

{% endtab %}

{% tab title="Groovy" %}

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

{% endtab %}
{% endtabs %}

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

Navegue até o `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 |

**Detector de documentos**

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

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

**Detector de documentos**

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

***

## Configurando a sessão

Para gerar seu token mobile, siga este guia:

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

Inicialize a Certta assim que tiver um token mobile válido (JWT) e um ID de 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: 'your-jwt',
          userId: 'user-id',
          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 mobile da CAF vindo do seu backend.                        |
| `userId`             | `string`                 | ID do usuário final.                                           |
| `environment`        | `CafEnvironment`         | Ambiente do backend: `PROD`, `BETA`, ou `DEV`.                 |
| `securityEnabled`    | `boolean`                | Ativa verificações de segurança. Padrão `true`.                |
| `colorConfiguration` | `CafColorConfiguration?` | Tema de cores opcional. Veja [Temas de cores](#color-theming). |

{% hint style="info" %}
`configureSDK` rejeita com `CerttaPlatformException` e código `BRIDGE_EXCEPTION` quando o mapper 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 toda a configuração:

```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 a Certta permaneça sincronizada 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]);
```

***

## Temas de cores

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

```typescript
await configureSDK({
  mobileToken: 'your-jwt',
  userId: 'user-id',
  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 as regras do ProGuard/R8 a `android/app/proguard-rules.pro` para que o SDK continue funcionando após a ofuscação. Veja o conjunto completo de regras em [Getting Started legado — Regras do ProGuard/R8](https://docs.caf.io/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](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/face-liveness.md)
{% endcontent-ref %}

{% content-ref url="/pages/1e1279259ffc8e30bf8c30a7c687900fe4ab864f" %}
[Document Detector](https://docs.caf.io/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.
