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

# Personalizações de UI

{% hint style="warning" %}
Este guia abrange a versão 7.14.0 e superior. Para versões anteriores à 7.14.0, consulte a [documentação legada](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% endhint %}

## Visão geral

**Detector de Documentos** oferece opções para personalizar sua interface, incluindo cores, layout e texto. A personalização é opcional porque valores padrão são fornecidos. Modifique apenas os elementos que você deseja alterar.

Há duas configurações de personalização, dependendo do módulo que você adicionar ao seu projeto: `document-detector` ou `document-detector-ui`. Para instruções detalhadas sobre como configurar o módulo, consulte o guia de instalação.

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

## Selecionando documentos para captura

Configure os documentos específicos que os usuários têm permissão para processar. Documentos físicos podem ser capturados pela câmera ou enviados (se habilitado), enquanto documentos virtuais devem sempre ser enviados.

{% hint style="info" %}
Ao usar o `document-detector-ui` módulo, os usuários veem uma lista de documentos permitidos para que possam escolher qual capturar.
{% endhint %}

Para configurar os documentos permitidos, atualize o `o fluxo` parâmetro em `DocumentDetectorConfiguration`. Se você estiver usando o `document-detector-ui` módulo, defina a `documentSelectionScreen` propriedade diretamente na sua `DocumentDetectorUiConfiguration`.

{% tabs fullWidth="false" %}
{% tab title="DocumentDetector" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(Document.RG_FRONT), 
        DocumentDetectorStep(Document.RG_BACK)
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endtab %}

{% tab title="DocumentDetectorUi" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront(), CafDocument.RGBack()),
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) {  }
```

{% endtab %}
{% endtabs %}

### Personalização do popup de orientação

Um popup de orientação é exibido ao usuário antes que a câmera ou a galeria de arquivos seja aberta. Para personalizar esse popup, defina um texto específico para cada tipo de documento usando o `DocumentDetectorStep` objeto.

{% hint style="warning" %}
A personalização do popup só é compatível ao usar o `document-detector` módulo e não está disponível em `document-detector-ui`.
{% endhint %}

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "Frente do cartão de identidade",
            "https://picsum.photos/400",
            "Coloque o documento sobre uma mesa",
            "Ok"
        )
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endcode %}

{% hint style="info" %}
Se `showPopup` is `true`, os detalhes da personalização são exibidos em um popup de orientação. Se os envios estiverem habilitados ou `showPopup` is `false`, esse popup é ignorado e os detalhes são aplicados ao popup de envio em vez disso.
{% endhint %}

### Personalização da tela de seleção de documentos

Ao usar o `document-detector-ui` módulo, você pode personalizar a Tela de Seleção de Documentos modificando o título e a descrição principais, तसे como os títulos e descrições individuais de cada documento na lista.

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(
            CafDocument.RGFront(
                stepLabel = "Frente do cartão de identidade",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Coloque o documento sobre uma mesa",
                stepOkButton = "Confirmar"
            ),
        ),
        title = "Escolha um documento",
        description = "Selecione o documento que deseja usar",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "Cartão de identidade",
                description = "Carteira de identidade"
            ),
        )
    ),
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) { }
```

{% endcode %}

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

O `document-detector-ui` módulo apresenta uma tela de instruções que aparece logo antes de a câmera ou a galeria de arquivos ser aberta. Tanto o texto quanto as imagens dessa tela são totalmente personalizáveis.

Você pode personalizar as telas de captura e envio individualmente passando uma instância de `CafDocumentDetectorInstructionsScreen` para a propriedade `instructionsScreen` .

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
     documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
          documents = listOf(CafDocument.RGFront()),
     ),
     instructionsScreen = CafDocumentDetectorInstructionsScreen(
          captureImage = "https://yourdomain.com/images/capture-guide.png",
          captureTitle = "Prepare-se para digitalizar",
          captureSteps = listOf("Encontre uma boa iluminação", "Posicione o documento dentro do enquadramento", "Evite reflexos"),

          uploadImage = "https://yourdomain.com/images/upload-guide.png",
          uploadTitle = "Envie seu documento",
          uploadSteps = listOf("Certifique-se de que o arquivo esteja nítido", "Deve ser JPG ou PNG", "Tamanho máximo de 5 MB"),

          buttonText = "Estou pronto"
     ),
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) {  }
```

{% endcode %}

### Parâmetros da tela de instruções

Todas as propriedades na `CafDocumentDetectorInstructionsScreen` classe são opcionais. Se deixadas como `null`, o SDK usará os valores padrão.

| Propriedade    | Descrição                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `captureImage` | A URL ou caminho do recurso da imagem exibida na tela de instruções de captura pela câmera.              |
| `captureTitle` | O texto do título principal exibido antes de o usuário abrir a câmera.                                   |
| `captureSteps` | Uma lista de etapas ou dicas de instrução para orientar o usuário sobre como tirar uma boa foto.         |
| `uploadImage`  | A URL ou caminho do recurso da imagem exibida na tela de instruções de envio de arquivo.                 |
| `uploadTitle`  | O texto do título principal exibido antes de o usuário selecionar um arquivo para enviar.                |
| `uploadSteps`  | Uma lista de etapas ou dicas de instrução para orientar o usuário na escolha de um arquivo válido.       |
| `buttonText`   | O texto exibido no botão que o usuário toca para prosseguir para a câmera ou para a galeria de arquivos. |

## Pré-visualização da foto

Permite que os usuários visualizem a imagem durante a captura do documento, possibilitando confirmar ou refazer a foto conforme necessário.

Para exibir a pré-visualização, defina `showPreview = true` em qualquer um dos `DocumentDetectorConfiguration` ou `DocumentDetectorUiConfiguration`.

### Personalização da tela de pré-visualização

Para personalizar a tela de pré-visualização, inclua `previewCustomization` no `customização` parâmetros.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    previewCustomization = CafPreviewCustomization(
        title = "Confirmar qualidade da foto",
        message = "Certifique-se de que todos os detalhes estejam claros e não haja reflexos.",
        okButton = "Confirmar",
        tryAgainButton = "Capturar novamente"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    showPreview = true,
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endcode %}

### Parâmetros das personalizações da pré-visualização

Todas as propriedades na `CafPreviewCustomization` classe são opcionais. Se deixadas como `null`, o SDK usará os valores padrão.

| Propriedade      | Descrição                                                 | Padrão (localizado)                                   |
| ---------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| `título`         | Texto do título na tela de pré-visualização.              | "A foto está boa?"                                    |
| `message`        | Texto do subtítulo/mensagem na tela de pré-visualização.  | "Verifique se todas as informações estão legíveis..." |
| `okButton`       | Texto para o botão de confirmação ("aceitar").            | "Sim, está boa!"                                      |
| `tryAgainButton` | Texto para o botão de tentar novamente ("tirar de novo"). | "Tirar novamente"                                     |

## Envio de documento

Permite que os usuários enviem um arquivo de imagem diretamente do dispositivo. Ao usar o `document-detector-ui` módulo, os usuários podem tirar uma nova foto ou enviar uma imagem existente.

{% hint style="info" %}
Ao contrário do módulo de UI, usar `document-detector` com os envios habilitados ocultará a opção de captura pela câmera.
{% endhint %}

{% hint style="warning" %}
A configuração de envio se aplica apenas a documentos físicos. Para documentos virtuais, os envios estão sempre habilitados por padrão.
{% endhint %}

Para habilitar a opção de envio, passe `true` para `as configurações de upload` em qualquer um dos `DocumentDetectorConfiguration` ou `DocumentDetectorUiConfiguration`.

### Personalização da tela de envio

Para personalizar o texto e a aparência da interface de envio, passe o objeto `uploadCustomization` em seu `customização` parâmetro.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    uploadCustomization = CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Escolha um arquivo para enviar",
        message = "Escolha o arquivo de documento que deseja enviar.",
        uploadButton = "Enviar arquivo",
        cancelButton = "Cancelar",
    ),
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Parâmetros das personalizações de envio

Todas as propriedades na `CafDDUploadCustomization` classe são opcionais. Se deixadas como `null`, o SDK usará os valores padrão.

<table><thead><tr><th width="187">Propriedade</th><th>Descrição</th><th>Padrão (localizado)</th></tr></thead><tbody><tr><td><code>imagem</code></td><td>Imagem exibida no topo do popup.</td><td>Ilustração padrão do SDK</td></tr><tr><td><code>título</code></td><td>O texto do título exibido na caixa de diálogo de envio.</td><td>O nome do documento selecionado (por exemplo, RG - Frente)</td></tr><tr><td><code>message</code></td><td>Texto da mensagem dentro do popup de envio.</td><td>"Selecione o arquivo..."</td></tr><tr><td><code>uploadButton</code></td><td>Texto para o botão "Enviar".</td><td>"Enviar"</td></tr><tr><td><code>cancelButton</code></td><td>Texto para o botão "Cancelar".</td><td>"Cancelar"</td></tr></tbody></table>

## Tentativas de repetição

Configure o número máximo de tentativas de repetição que um usuário tem antes de o processo ser interrompido e uma mensagem de erro ser exibida.

Para configurar o número de tentativas de repetição, defina `maxRetryAttempts` em qualquer um dos `DocumentDetectorConfiguration` ou `DocumentDetectorUiConfiguration`. O valor padrão é 3; defini-lo como -1 permite tentativas ilimitadas.

### Personalização da tela de tentativas de repetição

Para personalizar o texto e a aparência da interface de repetição, passe o `retryCustomization` em seu `customização` parâmetro.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    retryCustomization = CafDDRetryCustomization(
        title = "Ocorreu um erro",
        description = "Verifique sua conexão com a internet e tente novamente",
        textButton = "Tentar novamente"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Parâmetros de tentativas de repetição

Todas as propriedades na `CafDDRetryCustomization` classe são opcionais. Se deixadas como `null`, o SDK usará os valores padrão.

| Propriedade  | Descrição                                               | Padrão (localizado)                                      |
| ------------ | ------------------------------------------------------- | -------------------------------------------------------- |
| `título`     | Texto do título na tela de repetição.                   | "Foto não enviada"                                       |
| `descrição`  | Texto do subtítulo ou da mensagem na tela de repetição. | "Verifique sua conexão com a internet e tente novamente" |
| `textButton` | Texto para o botão de repetição.                        | "Tentar novamente"                                       |

## Personalização de mensagens de feedback

Você pode personalizar as mensagens exibidas no fluxo durante o processo de captura do documento (por exemplo, mensagens do sensor, feedback da IA).

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Por favor, aguarde...",
        fitTheDocumentMessage = "Alinhe seu documento dentro do enquadramento.",
        // outras mensagens
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Parâmetros de personalização de mensagens

Todas as propriedades na `CafMessageCustomization` classe são opcionais (`String?`). Se deixadas como `null`, o SDK usará os valores padrão.

| Propriedade                    | Descrição                                                                        |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `waitMessage`                  | Mensagem exibida ao iniciar a câmera.                                            |
| `fitTheDocumentMessage`        | Mensagem que solicita ao usuário que ajuste o documento dentro do enquadramento. |
| `holdItMessage`                | Mensagem exibida durante o processo de captura.                                  |
| `verifyingQualityMessage`      | Mensagem exibida durante a solicitação de verificação de qualidade.              |
| `lowQualityDocumentMessage`    | Mensagem exibida quando a captura do documento falha devido à baixa qualidade.   |
| `uploadingImageMessage`        | Mensagem exibida ao salvar a imagem capturada no servidor.                       |
| `openDocumentWrongMessage`     | Mensagem exibida se um documento aberto for detectado.                           |
| `unsupportedDocumentMessage`   | Mensagem para documentos não suportados.                                         |
| `documentNotFoundMessage`      | Mensagem exibida quando nenhum documento é detectado.                            |
| `sensorLuminosityMessage`      | Mensagem exibida quando o nível de brilho está muito baixo.                      |
| `sensorOrientationMessage`     | Mensagem exibida quando o limite de orientação não é atendido.                   |
| `sensorStabilityMessage`       | Mensagem exibida quando o dispositivo não está estável o suficiente.             |
| `popupDocumentSubtitleMessage` | Mensagem de subtítulo exibida no popup que apresenta a ilustração do documento.  |
| `positiveButtonMessage`        | Mensagem exibida no botão de confirmação.                                        |
| `aiScanDocumentMessage`        | Mensagem que solicita ao usuário que digitalize um documento.                    |
| `aiGetCloserMessage`           | Mensagem que solicita ao usuário que se aproxime do documento.                   |
| `aiCentralizeMessage`          | Mensagem que solicita ao usuário que centralize o documento na tela.             |
| `aiMoveAwayMessage`            | Mensagem que solicita ao usuário que se afaste do documento.                     |
| `aiAlignMessage`               | Mensagem que solicita ao usuário que alinhe o documento.                         |
| `aiTurnDocumentMessage`        | Mensagem que solicita ao usuário que gire o documento em 90 graus.               |
| `aiCapturedMessage`            | Mensagem que confirma que o documento foi capturado.                             |
| `wrongDocumentMessage`         | Mensagem exibida quando o tipo de documento está incorreto.                      |

## Personalização de mensagens de envio

Personalize as mensagens exibidas ao usuário enquanto a imagem está sendo enviada ao servidor.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Enviando seu documento...",
        documentVerifyingIntegrity = "Verificando a qualidade da imagem...",
        documentProcessingData = "Extraindo dados...",
        documentAlmostDone = "Finalizando..."
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

#### Parâmetros das mensagens de envio

Todas as propriedades na `CafDDUploadMessageCustomization` classe são opcionais (`String?`). Se deixadas como `null`, o SDK usará os valores padrão.

| Propriedade                  | Descrição                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `documentSending`            | O texto exibido quando o envio do documento começa e ele está sendo transmitido ao servidor.                       |
| `documentVerifyingIntegrity` | O texto mostrado enquanto o sistema verifica a qualidade e a validade do documento enviado.                        |
| `documentProcessingData`     | O texto exibido enquanto o backend está analisando ativamente o documento e extraindo seus dados.                  |
| `documentAlmostDone`         | O texto mostrado nas etapas finais do processo de envio e verificação, informando ao usuário que está finalizando. |

## Exemplo completo de personalização

### `DocumentDetectorCustomization`

Veja o exemplo abaixo para uma `DocumentDetectorCustomization` implementação completa com todas as personalizações disponíveis configuradas.

{% hint style="info" %}
Todos os campos desta configuração são opcionais e têm valores padrão predefinidos. Você só precisa fornecer valores para os campos específicos que deseja personalizar.
{% endhint %}

{% code expandable="true" %}

```kotlin
private val customization = DocumentDetectorCustomization(
    previewCustomization = CafDDCustomization.CafPreviewCustomization(
        title = "Confirmar qualidade da foto",
        message = "Certifique-se de que todos os detalhes estejam claros e não haja reflexos.",
        okButton = "Confirmar",
        tryAgainButton = "Capturar novamente"
    ),
    uploadCustomization = CafDDCustomization.CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Escolha um arquivo para enviar",
        message = "Escolha o arquivo de documento que deseja enviar.",
        uploadButton = "Enviar arquivo",
        cancelButton = "Cancelar",
    ),
    retryCustomization = CafDDCustomization.CafDDRetryCustomization(
        title = "Ocorreu um erro",
        description = "Verifique sua conexão com a internet e tente novamente",
        textButton = "Tentar novamente"
    ),
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Por favor, aguarde...",
        fitTheDocumentMessage = "Alinhe seu documento dentro do enquadramento.",
    ),
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Enviando seu documento...",
        documentVerifyingIntegrity = "Verificando a qualidade da imagem...",
        documentProcessingData = "Extraindo dados...",
        documentAlmostDone = "Finalizando..."
    )
)
```

{% endcode %}

### Lançando um Detector de Documentos personalizado

O exemplo a seguir demonstra como inicializar e lançar o `DocumentDetector` com todas as personalizações disponíveis aplicadas.

{% tabs %}
{% tab title="DocumentDetector" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "Frente do cartão de identidade",
            "https://picsum.photos/400",
            "Coloque o documento sobre uma mesa",
            "Ok"
        )
    ),
    customization = customization,
    showPopup = true,
    showPreview = true,
    uploadSettings = UploadSettings(true),
    requestTimeout = 60,
    maxRetryAttempts = 3,
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endtab %}

{% tab title="DocumentDetectorUi" %}
{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(
            CafDocument.RGFront(
                stepLabel = "Frente do cartão de identidade",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Coloque o documento sobre uma mesa",
                stepOkButton = "Confirmar"
            ),
        ),
        title = "Escolha um documento",
        description = "Selecione o documento que deseja usar",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "Cartão de identidade",
                description = "Carteira de identidade"
            ),
        )
    ),
    instructionsScreen = CafDocumentDetectorInstructionsScreen(
        captureImage = "https://yourdomain.com/images/capture-guide.png",
        captureTitle = "Prepare-se para digitalizar",
        captureSteps = listOf("Encontre uma boa iluminação", "Posicione o documento dentro do enquadramento", "Evite reflexos"),

        uploadImage = "https://yourdomain.com/images/upload-guide.png",
        uploadTitle = "Envie seu documento",
        uploadSteps = listOf("Certifique-se de que o arquivo esteja nítido", "Deve ser JPG ou PNG", "Tamanho máximo de 5 MB"),

        buttonText = "Estou pronto"
    ),
    showPopup = true,
    customization = customization
)
CerttaDocumentDetectorUi.instance.open(config) { }
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/document-detector/ui-customizations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.