> 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/document-detector/ui-customizations.md).

# Personalizações da UI

Personalize o Document Detector para Flutter. Aprenda como configurar a seleção de documento, telas de orientação, pré-visualizações, uploads, estados de tentativa novamente e mensagens no fluxo.

{% hint style="warning" %}
Este guia aborda **caf\_sdk 2.4.0** e superiores (Certta DevX). Para a versão anterior `CafSdk` fluxo sequencial, consulte a [documentação legada](https://docs.caf.io/caf-sdk/flutter/getting-started-with-the-sdk).
{% endhint %}

## Visão geral

O Document Detector pode personalizar os textos da interface, ilustrações e mensagens no fluxo. A personalização é opcional; defina apenas os campos que você quer alterar.

Existem duas configurações, dependendo do módulo que você habilitar em `caf-modules-config.json`: `documentDetector` ou `documentDetectorUI`.

{% content-ref url="/pages/d82530ac6e7f99d44e236a0f308e73c6cf5d0223" %}
[Guia de Instalação](/caf-sdk/caf-sdk-pt-br/flutter/installation-guide.md)
{% endcontent-ref %}

## Selecionando documentos para capturar

Configure os documentos que os usuários podem processar com `flow`. Documentos físicos podem ser capturados pela câmera ou enviados (se habilitado). Documentos virtuais devem ser enviados.

{% hint style="info" %}
Com o módulo UI, os usuários veem uma lista de documentos permitidos derivada de `flow`.
{% endhint %}

```dart
// Sem interface
final config = CerttaDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  showPopup: true,
);

// Módulo UI — os documentos ainda vêm de flow
final uiConfig = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  showPopup: true,
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Escolha um documento',
    description: 'Selecione o documento que você quer usar',
  ),
);
```

### Personalização do pop-up de orientação

Um pop-up de orientação é exibido antes de abrir a câmera ou a galeria de arquivos. Personalize-o por etapa em `CafDocumentDetectorFlow`.

{% hint style="warning" %}
A personalização do pop-up se aplica ao módulo sem interface `documentDetector` module. Não está disponível em `documentDetectorUI`.
{% endhint %}

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'Frente do RG',
      illustration: 'https://picsum.photos/400',
      message: 'Coloque o documento sobre uma mesa',
      okButtonTitle: 'Ok',
    ),
  ],
  showPopup: true,
);
```

{% hint style="info" %}
Se `showPopup` é `true`, esses detalhes aparecem em um pop-up de orientação. Se os envios estiverem ativados ou `showPopup` é `false`, o pop-up é ignorado e os detalhes se aplicam ao pop-up de envio em vez disso.
{% endhint %}

### Tela de seleção de documento

Com o módulo UI, personalize o título e a descrição do seletor. A lista de documentos em si é construída a partir de `flow`.

```dart
final config = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'Frente do RG',
      illustration: 'https://picsum.photos/400',
      message: 'Coloque o documento sobre uma mesa',
      okButtonTitle: 'Confirmar',
    ),
  ],
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Escolha um documento',
    description: 'Selecione o documento que você quer usar',
  ),
);
```

## Personalização da tela de instruções

O módulo UI pode exibir uma tela de instruções antes da câmera ou da galeria de arquivos. Personalize separadamente os textos de captura e envio.

```dart
final config = CerttaDocumentDetectorUiConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  instructionScreen: const CafDocumentDetectorUIInstructionScreenConfiguration(
    enable: true,
    captureImage: 'https://yourdomain.com/images/capture-guide.png',
    captureTitle: 'Prepare-se para digitalizar',
    captureSteps: [
      'Encontre uma boa iluminação',
      'Posicione o documento dentro da moldura',
      'Evite reflexos',
    ],
    uploadImage: 'https://yourdomain.com/images/upload-guide.png',
    uploadTitle: 'Envie seu documento',
    uploadSteps: [
      'Certifique-se de que o arquivo esteja nítido',
      'Deve ser JPG ou PNG',
      'Tamanho máximo de 5 MB',
    ],
    buttonText: "Estou pronto",
  ),
);
```

Todos os campos são opcionais. Se omitidos, o SDK usa os padrões.

| Propriedade    | Descrição                                                 |
| -------------- | --------------------------------------------------------- |
| `enable`       | Mostra ou oculta a tela de instruções. Padrão `true`.     |
| `captureImage` | URL ou recurso local para a tela de instruções da câmera. |
| `captureTitle` | Título exibido antes de a câmera abrir.                   |
| `captureSteps` | Dicas para tirar uma boa foto.                            |
| `uploadImage`  | URL ou recurso local para a tela de instruções de envio.  |
| `uploadTitle`  | Título exibido antes de o usuário escolher um arquivo.    |
| `uploadSteps`  | Dicas para escolher um arquivo válido.                    |
| `buttonText`   | Rótulo do botão que continua para a câmera ou a galeria.  |

## Pré-visualização da foto

Defina `showPreview: true` para permitir que os usuários confirmem ou tirem a foto novamente.

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  showPreview: true,
  previewCustomization: const CafDocumentDetectorPreviewCustomization(
    title: 'Confirme a qualidade da foto',
    message: 'Certifique-se de que todos os detalhes estejam nítidos e não haja reflexos.',
    okButton: 'Confirmar',
    tryAgainButton: 'Capturar novamente',
  ),
);
```

| Propriedade      | Descrição                                    |
| ---------------- | -------------------------------------------- |
| `title`          | Texto do título na tela de pré-visualização. |
| `message`        | Subtítulo na tela de pré-visualização.       |
| `okButton`       | Rótulo do botão de confirmação.              |
| `tryAgainButton` | Rótulo do botão de tentar novamente.         |

## Envio de documento

Ative o envio com `CafDocumentDetectorUploadSettings`.

{% hint style="info" %}
Ao contrário do módulo UI, usar o módulo sem interface `documentDetector` com envios ativados oculta a opção de captura pela câmera.
{% endhint %}

{% hint style="warning" %}
As configurações de envio se aplicam a documentos físicos. Documentos virtuais sempre permitem envio.
{% endhint %}

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  uploadSettings: const CafDocumentDetectorUploadSettings(
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.png, CafFileFormat.jpg],
    maxFileSize: 5,
  ),
  uploadCustomization: const CafDocumentDetectorUploadCustomization(
    image: 'https://picsum.photos/400',
    message: 'Escolha o arquivo do documento que você quer enviar.',
    uploadButton: 'Enviar arquivo',
    cancelButton: 'Cancelar',
  ),
);
```

| Propriedade    | Descrição                           |
| -------------- | ----------------------------------- |
| `image`        | Imagem no topo do pop-up de envio.  |
| `message`      | Mensagem dentro do pop-up de envio. |
| `uploadButton` | Rótulo do botão de envio.           |
| `cancelButton` | Rótulo do botão de cancelamento.    |

## Tentativas de repetição

`maxRetryAttempts` padrão para `3`. Use `-1` para tentativas ilimitadas.

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  maxRetryAttempts: 3,
  retryCustomization: const CafDocumentDetectorRetryCustomization(
    title: 'Ocorreu um erro',
    description: 'Verifique sua conexão com a internet e tente novamente',
    textButton: 'Tentar novamente',
  ),
);
```

| Propriedade   | Descrição                            |
| ------------- | ------------------------------------ |
| `title`       | Título na tela de nova tentativa.    |
| `description` | Subtítulo na tela de nova tentativa. |
| `textButton`  | Rótulo do botão de tentar novamente. |

## Mensagens de feedback

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  messageCustomization: const CafDocumentDetectorMessageCustomization(
    waitMessage: 'Aguarde...',
    fitTheDocumentMessage: 'Alinhe seu 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',
  ),
);
```

| Propriedade                     | Descrição                                          |
| ------------------------------- | -------------------------------------------------- |
| `waitMessage`                   | Exibida ao iniciar a câmera.                       |
| `fitTheDocumentMessage`         | Solicitação para encaixar o documento na moldura.  |
| `holdItMessage`                 | Exibida durante a captura.                         |
| `verifyingQualityMessage`       | Exibida durante a verificação de qualidade.        |
| `lowQualityDocumentMessage`     | Exibida quando a qualidade é muito baixa.          |
| `uploadingImageMessage`         | Exibida enquanto a imagem é salva.                 |
| `openDocumentWrongMessage`      | Exibida se um documento aberto for detectado.      |
| `unsupportedDocumentMessage`    | Exibida para documentos não suportados.            |
| `documentNotFoundMessage`       | Exibida quando nenhum documento é detectado.       |
| `sensorLuminosityMessage`       | Exibida quando a luminosidade está muito baixa.    |
| `sensorOrientationMessage`      | Exibida quando a orientação está incorreta.        |
| `sensorStabilityMessage`        | Exibida quando o dispositivo não está estável.     |
| `popupDocumentSubtitleMessage`  | Subtítulo no pop-up de ilustração do documento.    |
| `positiveButtonMessage`         | Rótulo do botão de confirmação.                    |
| `wrongDocumentMessage`          | Exibida quando o tipo de documento está incorreto. |
| `predictorScanDocumentMessage`  | Solicitação para escanear um documento.            |
| `predictorGetCloserMessage`     | Solicitação para chegar mais perto.                |
| `predictorCentralizeMessage`    | Solicitação para centralizar o documento.          |
| `predictorMoveAwayMessage`      | Solicitação para se afastar.                       |
| `predictorAlignDocumentMessage` | Solicitação para alinhar o documento.              |
| `predictorTurnDocumentMessage`  | Solicitação para girar o documento.                |
| `predictorCapturedMessage`      | Confirmação de que o documento foi capturado.      |

## Mensagens de progresso do envio

```dart
final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
  uploadMessagesCustomization:
      const CafDocumentDetectorUploadMessagesCustomization(
    sending: 'Enviando seu documento...',
    verifyingIntegrity: 'Verificando a qualidade da imagem...',
    processingData: 'Extraindo dados...',
    almostDone: 'Finalizando...',
  ),
);
```

| Propriedade          | Descrição                                                  |
| -------------------- | ---------------------------------------------------------- |
| `sending`            | Exibida quando o envio começa.                             |
| `verifyingIntegrity` | Exibida enquanto a qualidade e a validade são verificadas. |
| `processingData`     | Exibida enquanto o backend extrai os dados.                |
| `almostDone`         | Exibida na etapa final da verificação.                     |

## Exemplo completo de personalização

{% hint style="info" %}
Todos os campos de personalização são opcionais.
{% endhint %}

```dart
final certta = CerttaSdk();

await certta.documentDetector.open(
  CerttaDocumentDetectorConfiguration(
    flow: [
      CafDocumentDetectorFlow(
        document: CafDocument.rgFront,
        stepLabel: 'Frente do RG',
        illustration: 'https://picsum.photos/400',
        message: 'Coloque o documento sobre uma mesa',
        okButtonTitle: 'Ok',
      ),
    ],
    showPopup: true,
    showPreview: true,
    maxRetryAttempts: 3,
    requestTimeout: 60,
    uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
    previewCustomization: const CafDocumentDetectorPreviewCustomization(
      title: 'Confirme a qualidade da foto',
      message: 'Certifique-se de que todos os detalhes estejam nítidos e não haja reflexos.',
      okButton: 'Confirmar',
      tryAgainButton: 'Capturar novamente',
    ),
    uploadCustomization: const CafDocumentDetectorUploadCustomization(
      image: 'https://picsum.photos/400',
      message: 'Escolha o arquivo do documento que você quer enviar.',
      uploadButton: 'Enviar arquivo',
      cancelButton: 'Cancelar',
    ),
    retryCustomization: const CafDocumentDetectorRetryCustomization(
      title: 'Ocorreu um erro',
      description: 'Verifique sua conexão com a internet e tente novamente',
      textButton: 'Tentar novamente',
    ),
    messageCustomization: const CafDocumentDetectorMessageCustomization(
      waitMessage: 'Aguarde...',
      fitTheDocumentMessage: 'Alinhe seu documento dentro da moldura.',
    ),
    uploadMessagesCustomization:
        const CafDocumentDetectorUploadMessagesCustomization(
      sending: 'Enviando seu documento...',
      verifyingIntegrity: 'Verificando a qualidade da imagem...',
      processingData: 'Extraindo dados...',
      almostDone: 'Finalizando...',
    ),
  ),
);
```


---

# 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/document-detector/ui-customizations.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.