> 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/flutter/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\_sdk 2.4.0** (configure a sessão uma vez, abra os módulos independentemente). Para a `CafSdk` API, continue usando este guia. Para adotar o DevX, consulte o [Guia de Instalação](/caf-sdk/caf-sdk-pt-br/flutter/installation-guide.md) e [Migrando do CafSdk](/caf-sdk/caf-sdk-pt-br/flutter/migrating-from-cafsdk.md).
{% endhint %}

## Sobre o CafSDK

Esta documentação técnica cobre a **implementação do CafSDK para Flutter**, 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

***

## Exemplo

Confira o [aplicativo de exemplo](https://github.com/combateafraude/caf-sdk-flutter-exemple) para um exemplo completo de implementação.

***

## Instalação

### Requisitos

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

#### Flutter

| Requisito             | Versão |
| --------------------- | ------ |
| **Versão do Flutter** | 3.3.0+ |
| **Dart**              | 3.9.0+ |

#### 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.8+   |
| **Gradle**                                              | 8.0+   |
| **Android Gradle Plugin (AGP)**                         | 8.0+   |

#### iOS

| Requisito                         | Versão |
| --------------------------------- | ------ |
| **Destino de implantação do iOS** | 15.0+  |
| **Xcode**                         | 14.0+  |
| **Swift**                         | 5.0+   |

### Etapa 1: Instale o SDK

Instale o pacote principal do SDK:

```sh
flutter pub add caf_sdk
```

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

Crie um `caf-modules-config.json` arquivo na raiz do seu projeto para especificar quais módulos incluir:

> **Observação**: Se você omitir este arquivo, todos os módulos serão habilitados por padrão e **`iproov-lite`** é usado como o provedor padrão de Face Liveness.

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

Defina como `true` os módulos que você deseja usar no seu aplicativo.

Para um único provedor, `livenessProviders` pode ser uma string. Os valores permitidos são `iproov-lite`, `iproov-full`, `payface`e `facetec`. Para usar vários provedores, use um array (veja o exemplo abaixo).

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

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

Você pode declarar **mais de um** provedor definindo `livenessProviders` como um array quando sua integração exigir isso.

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

Defina como `true` os módulos que você deseja usar no seu aplicativo.

**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 Android

#### Adicionar repositórios Maven

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

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

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

{% endtab %}

{% tab title="Groovy" %}

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

{% endtab %}
{% endtabs %}

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

Acesse o `diretório ios/` do seu projeto Flutter 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:

```dart
import 'dart:async';
import 'package:caf_sdk/types/index.dart';
import 'package:flutter/material.dart';
import 'package:caf_sdk/caf_sdk.dart';

void main() => runApp(const App());

class App extends StatelessWidget {
  const App({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Exemplo de CAF SDK',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const SimpleExamplePage(),
    );
  }
}

class SimpleExamplePage extends StatefulWidget {
  const SimpleExamplePage({super.key});

  @override
  State<SimpleExamplePage> createState() => _SimpleExamplePageState();
}

class _SimpleExamplePageState extends State<SimpleExamplePage> {
  final _cafSdk = CafSdk();
  StreamSubscription<CafResponse>? _eventSubscription;

  @override
  void initState() {
    super.initState();
    _initializeEventStream();
  }

  @override
  void dispose() {
    _eventSubscription?.cancel();
    super.dispose();
  }

  void _initializeEventStream() {
    _eventSubscription = _cafSdk.eventStream.listen((event) {
      if (!mounted) return;

      if (event.success != null) {
        print('Sucesso: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
      } else if (event.error != null) {
        print('Erro: ${event.error!.type} - ${event.error!.description}');
      } else if (event.failure != null) {
        print('Falha: ${event.failure!.type} - ${event.failure!.description}');
      }
    });
  }

  Future<void> _initialize() async {
    try {
      // Configuração do SDK
      final config = CafSdkConfiguration(
        mobileToken: 'token',
        personId: 'personId',
        environment: CafEnvironment.dev,
        configuration: CafSdkBuilderConfiguration(
          presentationOrder: [
            CafModuleType.faceLiveness,
            CafModuleType.documentDetector,
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
        ),
      );

      // Configuração do Face Liveness
      final faceLivenessConfig = CafFaceLivenessConfiguration(
        loading: true,
        debugModeEnabled: true,
        payFaceDebugMode: false,
      );

      // Configuração do Document Detector
      final documentDetectorConfig = CafDocumentDetectorConfiguration(
        flow: [
          CafDocumentDetectorFlow(document: CafDocument.rgFront),
          CafDocumentDetectorFlow(document: CafDocument.rgBack),
        ],
        uploadSettings: CafDocumentDetectorUploadSettings(enable: false),
        manualCaptureEnabled: false,
        manualCaptureTime: 45,
        showPopup: true,
        previewShow: false,
        securitySettings: CafDocumentDetectorSecuritySettings(
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        ),
      );

      await _cafSdk.initializeCafSdk(
        cafSdkConfiguration: config,
        faceLivenessConfiguration: faceLivenessConfig,
        documentDetectorConfiguration: documentDetectorConfig,
      );
    } catch (e) {
      print('Erro: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Exemplo simples do CAF SDK'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: SafeArea(
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.center,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Center(
                child: ElevatedButton(
                  onPressed: _initialize,
                  child: Text('Iniciar')
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

***

## 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 `CafSdk` classe serve como contêiner central para todas as configurações. Essa configuração define a ordem de execução dos módulos e a identidade visual.

**Parâmetros essenciais:**

* **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:**

```dart
final _cafSdk = CafSdk();

// Configuração do SDK
final config = CafSdkConfiguration(
  mobileToken: "mobile-token",
  personId: "person-id",
  environment: CafEnvironment.prod,
  configuration: CafSdkBuilderConfiguration(
    presentationOrder: [
      CafModuleType.faceLiveness,    // ou CafModuleType.faceLivenessUi
      CafModuleType.documentDetector // ou CafModuleType.documentDetectorUi
    ],
    enableSecurityModule: true,       // Opcional, o padrão é true
    waitForAllServices: true,         // Opcional, o padrão é true
    enableTransitionScreens: true,    // Opcional, o padrão é true
    colorConfiguration: CafColorConfiguration(
      primaryColor: "#0000FF",
      secondaryColor: "#00FF00",
      backgroundColor: "#FFFFFF",
      contentColor: "#000000",
      mediumColor: "#CCCCCC",
      dialogBackgroundColor: "#FFFFFF",
      dialogBorderColor: "#E5E5E7",
    ),
  ),
);

// Inicialize o SDK
await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
  documentDetectorConfiguration: documentDetectorConfig,
  documentDetectorUIConfiguration: documentDetectorUIConfig,
  faceLivenessConfiguration: faceLivenessConfig,
  faceLivenessUIConfiguration: faceLivenessUIConfig,
);
```

### Configuração específica do módulo

#### Configuração do Face Liveness

Você pode configurar o módulo Face Liveness criando uma `CafFaceLivenessConfiguration`. Ao usar o provedor opcional PayFace (Fortface), use `payFaceDebugMode` para ativar o modo de depuração para esse provedor.

```dart
final faceLivenessConfig = CafFaceLivenessConfiguration(
  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 повтор
  payFaceDebugMode: false,                                        // Opcional, ativa o modo de depuração para o provedor PayFace (Fortface)
);
```

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

Você pode configurar o módulo Detector de Documentos criando uma `CafDocumentDetectorConfiguration`:

```dart
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  securitySettings: CafDocumentDetectorSecuritySettings(
    useAdb: true,
    useDebug: true,
    useDevelopmentMode: true,
  ),
  manualCaptureEnabled: true,
  manualCaptureTime: 30,
  requestTimeout: 60,
  showPopup: true,
  maxRetryAttempts: 2,
  uploadSettings: CafDocumentDetectorUploadSettings(
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.png, CafFileFormat.jpg],
    maxFileSize: 5, // 5MB
  ),
);
```

***

## Tratamento de Eventos

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

A `eventStream` da `CafSdk` class fornece um **tipado** `Stream<CafResponse>` gerado durante a execução do fluxo de captura. Cada `CafResponse` tem exatamente um campo preenchido, que indica o tipo de evento:

| Campo       | Tipo                  | Descrição                                                                               |
| ----------- | --------------------- | --------------------------------------------------------------------------------------- |
| `loading`   | `bool`                | Indica o início do processamento do módulo                                              |
| `loaded`    | `bool`                | Indica que o módulo foi processado                                                      |
| `success`   | `CafSuccessResponse?` | Após a conclusão bem-sucedida; contém `moduleName` e `signedResponse`                   |
| `error`     | `CafErrorResponse?`   | Ocorreu um problema durante a execução; contém `type` e `description`                   |
| `failure`   | `CafFailureResponse?` | Indica uma falha de Face Liveness; contém `type`, `description`e `response`             |
| `log`       | `CafLog?`             | Mensagens de log com diferentes níveis; contém `level` (DEBUG, USAGE, INFO) e `message` |
| `cancelled` | `bool`                | Indica que o usuário ou o sistema interrompeu o fluxo                                   |

> **Nota de migração (v2.0.0):** `eventStream` agora emite objetos `CafResponse` tipados em vez de `Map` brutos. Substitua qualquer acesso a `event['eventName']` / `event['response']` pelos campos tipados mostrados acima.

**Exemplo de tratamento de eventos:**

```dart
final _cafSdk = CafSdk();
StreamSubscription<CafResponse>? _eventSubscription;

void _initializeEventStream() {
  _eventSubscription = _cafSdk.eventStream.listen((event) {
    if (!mounted) return;

    if (event.loading) {
      print('Carregando...');
    } else if (event.loaded) {
      print('Sessão carregada');
    } else if (event.success != null) {
      print('Sucesso: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
    } else if (event.error != null) {
      print('Erro: ${event.error!.type} - ${event.error!.description}');
    } else if (event.failure != null) {
      print('Falha: ${event.failure!.type} - ${event.failure!.description}');
    } else if (event.log != null) {
      print('Log: ${event.log!.level} - ${event.log!.message}');
    } else if (event.cancelled) {
      print('Cancelado pelo usuário');
    }
  });
}

@override
void dispose() {
  _eventSubscription?.cancel();
  super.dispose();
}
```

### 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                           |
| `INVALID_RESPONSE_EXCEPTION`       | Payload de resposta inválido recebido de um módulo       |
| `CAMERA_EXCEPTION`                 | Falha na inicialização ou em tempo de execução da câmera |
| `FACE_AUTHENTICATION`              | Erro durante a autenticação facial (executeFaceAuth)     |
| `BRIDGE_EXCEPTION`                 | Erro de comunicação na ponte nativa ↔ Flutter            |

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

```dart
final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  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,
  payFaceDebugMode: false,
  instructionScreen: CafFaceLivenessUIInstructionScreenConfiguration(
    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

```dart
final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)], 
  manualCaptureEnabled: true,
  manualCaptureTime: 45,
  requestTimeout: 60,
  showPopup: true,
  securitySettings: CafDocumentDetectorSecuritySettings(
    useDebug: true,
    useDevelopmentMode: true,
    useAdb: true,
  ),
  maxRetryAttempts: 2,
  instructionScreen: CafDocumentDetectorUIInstructionScreenConfiguration(
    enable: true,
    captureTitle: "Capture seu documento",
    captureSteps: [
      "Mantenha o telefone parado",
      "Garanta boa iluminação",
      "Evite reflexos"
    ],
    buttonText: "Iniciar",
  ),
  documentSelectionScreen: CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    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:

```dart
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  proxySettings: CafDocumentDetectorProxySettings(
    hostname: "proxy.example.com",
    port: 8080,
    authentication: CafDocumentDetectorProxySettingsAuthentication(
      user: "username",
      password: "password"
    ),
  ),
);
```

### Personalização de Mensagens

Personalize as mensagens exibidas durante o fluxo de captura:

```dart
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  messageCustomization: CafDocumentDetectorMessageCustomization(
    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:

```dart
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:caf_sdk/caf_sdk.dart';
import 'package:caf_sdk/types/index.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Exemplo de CAF SDK',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const CafSdkExamplePage(),
    );
  }
}

class CafSdkExamplePage extends StatefulWidget {
  const CafSdkExamplePage({super.key});

  @override
  State<CafSdkExamplePage> createState() => _CafSdkExamplePageState();
}

class _CafSdkExamplePageState extends State<CafSdkExamplePage> {
  final _cafSdk = CafSdk();
  StreamSubscription<CafResponse>? _eventSubscription;

  final String _mobileToken = "token";
  final String _personId = "personId";
  final CafEnvironment _environment = CafEnvironment.dev;

  @override
  void initState() {
    super.initState();
    _initializeEventStream();
  }

  @override
  void dispose() {
    _eventSubscription?.cancel();
    super.dispose();
  }

  void _initializeEventStream() {
    _eventSubscription = _cafSdk.eventStream.listen((event) {
      if (!mounted) return;

      if (event.loading) {
        print('[CAF SDK EVENT]: loading');
      } else if (event.loaded) {
        print('[CAF SDK EVENT]: loaded');
      } else if (event.success != null) {
        print('[CAF SDK EVENT]: success');
        print('[CAF SDK EVENT]: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
      } else if (event.error != null) {
        print('[CAF SDK EVENT]: error');
        print('[CAF SDK EVENT]: ${event.error!.type} - ${event.error!.description}');
      } else if (event.failure != null) {
        print('[CAF SDK EVENT]: failure');
        print('[CAF SDK EVENT]: ${event.failure!.type} - ${event.failure!.description}');
      } else if (event.log != null) {
        print('[CAF SDK EVENT]: log');
        print('[CAF SDK EVENT]: ${event.log!.level} - ${event.log!.message}');
      } else if (event.cancelled) {
        print('[CAF SDK EVENT]: cancelado');
      }
    });
  }

  Future<void> _initializeCafSdk() async {
    try {
      // Configuração do SDK
      final config = CafSdkConfiguration(
        mobileToken: _mobileToken,
        personId: _personId,
        environment: _environment,
        configuration: CafSdkBuilderConfiguration(
          presentationOrder: [
            CafModuleType.faceLivenessUi,
            CafModuleType.documentDetectorUi,
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
        ),
      );

      // Configuração da interface de usuário de Face Liveness
      CafFaceLivenessUIConfiguration?
      faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
        loading: true,
        debugModeEnabled: true,
        payFaceDebugMode: false,
        instructionScreen:
            CafFaceLivenessUIInstructionScreenConfiguration(
              title: "Vitalidade Facial",
              description:
                  "Posicione seu rosto no centro e siga as instruções",
              steps: [
                "Centralize seu rosto",
                "Siga as instruções",
                "Permaneça imóvel",
              ],
              buttonText: "Iniciar",
            ),
      );

      // Configuração da interface de usuário do Detector de Documentos
      CafDocumentDetectorUIConfiguration?
      documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
        flow: [
          CafDocumentDetectorFlow(document: CafDocument.rgFront),
          CafDocumentDetectorFlow(document: CafDocument.rgBack),
          CafDocumentDetectorFlow(document: CafDocument.rgFull),
          CafDocumentDetectorFlow(document: CafDocument.cnhFront),
          CafDocumentDetectorFlow(document: CafDocument.cnhBack),
          CafDocumentDetectorFlow(document: CafDocument.cnhFull),
          CafDocumentDetectorFlow(document: CafDocument.crlv),
          CafDocumentDetectorFlow(document: CafDocument.rneFront),
          CafDocumentDetectorFlow(document: CafDocument.rneBack),
          CafDocumentDetectorFlow(document: CafDocument.ctpsFront),
          CafDocumentDetectorFlow(document: CafDocument.ctpsBack),
          CafDocumentDetectorFlow(document: CafDocument.passport),
          CafDocumentDetectorFlow(document: CafDocument.any),
        ],
        uploadSettings: CafDocumentDetectorUploadSettings(enable: true),
        manualCaptureEnabled: false,
        manualCaptureTime: 45,
        showPopup: true,
        previewShow: false,
        securitySettings: CafDocumentDetectorSecuritySettings(
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        ),
        instructionScreen:
            CafDocumentDetectorUIInstructionScreenConfiguration(
              enable: true,
              captureTitle: "Título da captura",
              captureSteps: ["Etapa de captura 1", "Etapa de captura 2"],
              uploadTitle: "Título do envio",
              uploadSteps: ["Etapa de envio 1", "Etapa de envio 2"],
              buttonText: "Texto do botão",
            ),
        documentSelectionScreen:
            CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
              title: "Título da seleção de documento",
              description: "Descrição da seleção de documento",
            ),
      );

      await _cafSdk.initializeCafSdk(
        cafSdkConfiguration: config,
        documentDetectorUIConfiguration: documentDetectorUIConfig,
        faceLivenessUIConfiguration: faceLivenessUIConfig,
      );

      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text('SDK da CAF inicializado com sucesso!'),
            backgroundColor: Colors.green,
          ),
        );
      }
    } catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Erro: $e'), backgroundColor: Colors.red),
        );
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Exemplo do CAF SDK'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            _ConfigurationCard(
              mobileToken: _mobileToken,
              personId: _personId,
              environment: _environment,
            ),
            const SizedBox(height: 16),

            _ActionButtons(onInitialize: _initializeCafSdk),
            const SizedBox(height: 16),
          ],
        ),
      ),
    );
  }
}

class _ConfigurationCard extends StatelessWidget {
  const _ConfigurationCard({
    required this.mobileToken,
    required this.personId,
    required this.environment,
  });

  final String mobileToken;
  final String personId;
  final CafEnvironment environment;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              'Configuração do CAF SDK',
              style: Theme.of(context).textTheme.titleLarge,
            ),
            const SizedBox(height: 16),
            Text(
              'Token móvel: ${mobileToken.length > 20 ? '${mobileToken.substring(0, 20)}...' : mobileToken}',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
            const SizedBox(height: 8),
            Text(
              'ID da pessoa: $personId',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
            const SizedBox(height: 8),
            Text(
              'Ambiente: $environment',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
          ],
        ),
      ),
    );
  }
}

class _ActionButtons extends StatelessWidget {
  const _ActionButtons({
    required this.onInitialize,
  });

  final VoidCallback onInitialize;

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(
          child: ElevatedButton(
            onPressed: onInitialize,
            style: ElevatedButton.styleFrom(
              padding: const EdgeInsets.symmetric(vertical: 16),
              shape: RoundedRectangleBorder(
                borderRadius: BorderRadius.circular(8),
              ),
            ),
            child: Text('Inicializar SDK'),
          ),
        ),
        const SizedBox(width: 8),
      ],
    );
  }
}
```

***

## Regras do ProGuard/R8

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

```proguard
# Regras do Flutter ProGuard/R8 para o Caf SDK
# Estas regras garantem que o plugin CAF SDK funcione corretamente em builds de release

# O pré-handler Android para exceções é carregado por reflexão (via ServiceLoader).
-keep class kotlinx.coroutines.experimental.android.AndroidExceptionPreHandler { *; }

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

### Flutter Plugin ###########################################################
# Mantenha as classes do plugin Flutter
-keep class io.flutter.plugins.** { *; }

# Mantenha classes do canal de método
-keep class * extends io.flutter.plugin.common.MethodChannel$MethodCallHandler { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$Result { *; }

# Mantenha o registrador do plugin
-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }

# Mantenha as classes do plugin Flutter do CAF SDK
-keep class io.caf.sdk.flutter.** { *; }
### END Flutter Plugin #######################################################

### 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.** { *; }
# Preserve todas as classes do SDK FortFace/PayFace para evitar problemas de ofuscação
-keep class br.com.fortface.** { *; }
-keep interface br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.** { *; }
# Mantenha todas as classes internas e enums
-keepclassmembers class br.com.fortface.**$* { *; }
# Preserve completamente as classes JSON (crítico para o PayFace)
-keep class org.json.** { *; }
-keepclassmembers class org.json.** { *; }
# Preserve classes relacionadas a JSON usadas pelo SDK PayFace
-keepclassmembers class * {
    @org.json.** *;
}
# Suprima avisos para o SDK PayFace
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### END 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

***

## Notas de lançamento

Notas de lançamento de todas as `caf_sdk` versões, incluindo **2.4.0 (Certta DevX)** e o guia de migração da 1.x → 2.0.0, estão no changelog.

{% content-ref url="/pages/5e04e959321bcaa38f3bba34b3508f36ab84b0dd" %}
[Histórico de alterações](/caf-sdk/caf-sdk-pt-br/flutter/changelog.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/flutter/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.