> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-imagens.md).

# Personalização de imagens

Substitua a arte que o Smart Capture renderiza: moldura da câmera, ícones de navegação e ação, ícones de status, ilustrações de ajuda da câmera e as sequências animadas de instruções.

{% hint style="warning" %}
Em React Native:

* Android: adicione um drawable com o mesmo nome de recurso em `android/app/src/main/res/drawable/`. `imageCustomization` em `CerttaSmartCaptureConfiguration` é ignorado.
* iOS: passe strings URI em TypeScript (`imageCustomization` em `open()`). Resolva assets empacotados com `Image.resolveAssetSource(require(...)).uri`.
  {% endhint %}

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

### Visão geral

Cada ícone e ilustração no fluxo do Smart Capture é um drawable normal do Android com um ID de recurso fixo. Para substituir um deles, declare um drawable com o mesmo nome no módulo do app React Native Android:

`android/app/src/main/res/drawable/`\
ou uma variante qualificadora como `android/app/src/main/res/drawable-night/`.

O recurso do seu app vence na compilação. Nenhuma API em tempo de execução — `imageCustomization` no config TypeScript não faz nada no Android.

Os IDs de recurso são internos à versão atual do SDK nativo e podem mudar entre lançamentos. Verifique esta lista novamente após atualizar.

Tamanhos: corresponda ao tamanho listado para cada drawable. Vetores mantêm seu tamanho em dp, e `.webp` as imagens devem manter a proporção de aspecto (exporte com a mesma). Shapes não têm tamanho fixo: eles se esticam para caber em sua view.

O tipo de recurso deve corresponder (um drawable substitui outro drawable). A extensão do arquivo não importa: você pode substituir um vetor XML com um `.webp`/`.png` desde que o nome seja o mesmo.

### API

| Mecanismo                        | Onde                                 | Descrição                                                       |
| -------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
| Substituição de recurso drawable | `android/app/src/main/res/drawable/` | Arquivo (ou XML) cujo nome de recurso corresponde ao ID do SDK. |

Quando você não declara um determinado nome, o SDK usa sua própria arte.

android/app/src/main/res/drawable/certta\_sc\_arrow\_left.pngandroid/app/src/main/res/drawable/certta\_sc\_ic\_help.xml

### Adicionando suas imagens

1. Coloque o arquivo em `drawable/` (ou `drawable-night/`, `drawable-hdpi/`, …).
2. Use o nome de recurso exato das tabelas abaixo (sem `ic_` prefixo, a menos que o SDK já tenha um).
3. Recompile o app. Seu drawable substitui automaticamente o padrão do SDK.

Substituições parciais são suportadas: substitua apenas os espaços que importam para você.

### Ordem de resolução

Para cada drawable:

1. O drawable do seu app com esse ID de recurso (incluindo o qualificador que melhor corresponder).
2. O drawable empacotado do SDK.

Modo escuro: use `drawable-night/` se você precisar de um gráfico diferente. O Android resolve a aparência a partir de qualificadores de recurso, não do TypeScript.

### Botões e controles

| ID do recurso                       | Formato          | Tamanho          | Usado para                                    |
| ----------------------------------- | ---------------- | ---------------- | --------------------------------------------- |
| `certta_sc_camera_button_enabled`   | Vetor            | 71×71 dp         | Disparo — ativado                             |
| `certta_sc_camera_button_disabled`  | Vetor            | 71×71 dp         | Disparo — desativado                          |
| `certta_sc_camera_button_pressed`   | Vetor            | 71×71 dp         | Disparo — pressionado                         |
| `certta_sc_camera_button_selector`  | Lista de estados | 71×71 dp         | Combina os três estados do disparo            |
| `certta_sc_button_close_enabled`    | Vetor            | 40×40 dp         | Fechar (“X”) — ativado                        |
| `certta_sc_button_closed_pressed`   | Vetor            | 36×36 dp         | Fechar — pressionado (intencionalmente menor) |
| `certta_sc_close_button_selector`   | Lista de estados | 40×40 / 36×36 dp | Combina os estados do botão de fechar         |
| `certta_sc_close_icon`              | Vetor            | 12×12 dp         | Glifo de fechar (“X”)                         |
| `certta_sc_arrow_left`              | Vetor            | 32×32 dp         | Navegação de volta                            |
| `certta_sc_eye`                     | Vetor            | 44×44 dp         | “Visualizar arquivo” no Upload                |
| `certta_sc_trash`                   | Vetor            | 48×48 dp         | Excluir um arquivo enviado                    |
| `certta_sc_ic_help`                 | Vetor            | 48×48 dp         | Ajuda (“?”) na câmera e na permissão          |
| `certta_sc_ic_checkmark_small`      | Vetor            | 17×17 dp         | Marca de verificação pequena                  |
| `certta_sc_ic_loading_spin`         | Vetor            | 90×90 dp         | Carregador estático                           |
| `certta_sc_loading_animated_vector` | Vetor animado    | 90×90 dp         | Carregador animado                            |
| `certta_sc_dot_selector`            | Lista de estados | 12×12 dp         | Indicador de página nas instruções            |

### Fundos e contêineres

Essas formas se esticam para preencher sua view. Altere a forma, o raio ou o traço em vez de corresponder a um tamanho. Algumas bordas seguem recursos de cor (veja Personalização de cores).

| ID do recurso                                | Formato | Tamanho                       | Usado para                                                                        |
| -------------------------------------------- | ------- | ----------------------------- | --------------------------------------------------------------------------------- |
| `certta_sc_primary_button_background`        | Forma   | Adapta-se                     | Botão primário (preenchido)                                                       |
| `certta_sc_secondary_button_background`      | Forma   | Adapta-se (traço de 1 dp)     | Botão secundário (contorno). A borda segue `certta_sc_accent`                     |
| `certta_sc_attach_button_background`         | Forma   | Adapta-se (tracejado de 2 dp) | “Anexar documento” no Upload. A borda segue `certta_sc_accent`                    |
| `certta_sc_preview_retake_button_background` | Forma   | Adapta-se (traço de 1 dp)     | “Tirar outra foto” na Pré-visualização. A borda segue `certta_sc_secondary_color` |
| `certta_sc_bottom_sheet_background`          | Forma   | Adapta-se                     | Folha inferior. O preenchimento segue `certta_sc_dialog_background_color`         |
| `certta_sc_bottom_sheet_drag_handle`         | Forma   | Adapta-se                     | Alça de arrastar em folhas inferiores                                             |
| `certta_sc_camera_error_background_drawable` | Forma   | Adapta-se (traço de 1 dp)     | Banners de erro na câmera. O preenchimento/borda seguem as cores de aviso         |
| `certta_sc_instructions_hint_background`     | Forma   | Adapta-se                     | Cápsulas de dica de instrução                                                     |
| `certta_sc_validation_type_card_background`  | Forma   | Adapta-se (traço de 2 dp)     | Cartões do método de validação. A borda segue `certta_sc_dialog_border_color`     |

### Ícones e ilustrações específicos da tela

| ID do recurso                      | Formato       | Tamanho    | Usado para                                                       |
| ---------------------------------- | ------------- | ---------- | ---------------------------------------------------------------- |
| `certta_sc_camera_denied_icon`     | Raster (webp) | 312×84 px  | Permissão da câmera negada                                       |
| `certta_sc_dd_success_icon`        | Vetor         | 100×103 dp | Marca de verificação da tela de sucesso                          |
| `certta_sc_alert_triangle_icon`    | Vetor         | 19×17 dp   | Aviso em alertas. O preenchimento segue `certta_sc_warning_icon` |
| `certta_sc_camera_hint_drawable`   | Forma         | Adapta-se  | Dica sobreposta durante a captura                                |
| `certta_sc_doc_front`              | Vetor         | 164×112 dp | “Vire o documento” — frente                                      |
| `certta_sc_doc_back`               | Vetor         | 164×112 dp | “Vire o documento” — verso                                       |
| `certta_sc_validation_type_camera` | Vetor         | 24×24 dp   | Cartão “Tirar foto”                                              |
| `certta_sc_validation_type_upload` | Vetor         | 24×24 dp   | Cartão “Anexar documento”                                        |

### Dicas de ajuda (folha inferior de ajuda da câmera)

| ID do recurso                           | Formato       | Tamanho  | Usado para                    |
| --------------------------------------- | ------------- | -------- | ----------------------------- |
| `certta_sc_camera_help_hint_drawable_1` | Vetor         | 48×70 dp | Dica 1 — “Enquadre as bordas” |
| `certta_sc_camera_help_hint_drawable_2` | Raster (webp) | 48×69 px | Dica 2 — “Evite reflexos”     |
| `certta_sc_camera_help_hint_drawable_3` | Vetor         | 48×70 dp | Dica 3 — “Dados legíveis”     |

### Carrossel de instruções

Todas as imagens compartilham o mesmo tamanho de tela (124×168 px, raster webp). As imagens de uma dica fazem crossfade em loop, então substituir uma delas altera parte dessa animação, e não uma única imagem estática.

| ID do recurso                                          | Usado para                                        |
| ------------------------------------------------------ | ------------------------------------------------- |
| `certta_sc_capture_instructions_1_1` / `_1_2` / `_1_3` | Dica de captura 1 — “Comece por qualquer lado”    |
| `certta_sc_capture_instructions_2_1` / `_2_2`          | Dica de captura 2 — “Mantenha as bordas visíveis” |
| `certta_sc_capture_instructions_3_1` / `_3_2`          | Dica de captura 3 — “Garanta clareza”             |
| `certta_sc_upload_instructions_1_1` / `_1_2`           | Dica de upload 1 — “Envie imagem ou PDF”          |
| `certta_sc_upload_instructions_2_1` / `_2_2`           | Dica de upload 2 — “Envie um ou dois arquivos”    |

### O que não pode ser personalizado

A forma dos botões, cartões e folhas (raio da borda, largura do traço) é fixa, a menos que você substitua esse drawable. Cores sólidas ficam em Personalização de cores. Texto fica em Personalização de texto.

Se você definir um `certta_sc_background_color`, vários ícones mantêm seus preenchimentos escuros e fundos de botão brancos continuam brancos — substitua esses drawables também, ou mantenha os fundos claros padrão.
{% endtab %}

{% tab title="iOS" %}

### Visão geral

`CerttaSmartCaptureImageCustomization` substitui a arte que o Smart Capture renderiza: moldura da câmera, ícones de navegação e ação, ícones de status, ilustrações de ajuda da câmera e as sequências animadas de instruções.

Há 23 espaços — 18 imagens únicas e 5 sequências animadas. Cada espaço é opcional. Um espaço que você deixar sem definir mantém o asset empacotado.

### API

| TypeScript                                                  | Onde                                |
| ----------------------------------------------------------- | ----------------------------------- |
| `imageCustomization?: CerttaSmartCaptureImageCustomization` | `useCerttaSmartCapture().open(...)` |

Espaços únicos são `string` (URI). Espaços de sequência são `string[]` (URIs de frames na ordem).

```typescript
import { Image } from 'react-native';
import {
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const helpIcon = Image.resolveAssetSource(require('./assets/brand_help.png'));
const backArrow = Image.resolveAssetSource(require('./assets/brand_back.png'));

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [
    CerttaAcceptedDocumentType.IDENTITY_CARD,
    CerttaAcceptedDocumentType.DRIVER_LICENSE,
  ],
  imageCustomization: {
    helpIcon: helpIcon.uri,
    backArrow: backArrow.uri,
  },
};

await open(config);
```

`imageCustomization: {}` é válido e não produz efeito visual.

Os tokens são mapeados por significado, não pelo nome do asset. Marcar um ícone de aviso marca todas as superfícies de aviso; o mesmo vale para o glifo de fechar.

`closeButtonEnabled` / `closeButtonDisabled` e `closeIcon` são espaços diferentes. O primeiro par é o gráfico circular completo atrás do botão circular da câmera; `closeIcon` é o pequeno glifo X na folha de ajuda, na folha de exclusão de arquivo e na pré-visualização de upload.

### Adicionando suas imagens

1. Coloque PNG/WebP (e `@2x` / `@3x` se você usar um catálogo de assets no lado nativo, ou assets do Metro sensíveis à densidade) no bundle JS.
2. Resolva com `Image.resolveAssetSource(require(...)).uri`.
3. Atribua apenas os espaços que você quer alterar.

Remoto `https://` URIs só são confiáveis se o SDK nativo puder carregá-las no momento da abertura. Prefira assets empacotados.

### Ordem de resolução

Para cada espaço:

1. Sua substituição, quando o espaço estiver definido.
2. O asset nativo empacotado para esse espaço.
3. Nada — o espaço renderiza vazio.

Um array vazio em um espaço de sequência é tratado como não definido e usa como fallback a animação empacotada.

### Imagens únicas

Todos os 18 espaços são strings URI opcionais. A coluna Tamanho é o contêiner em que a imagem é posicionada.

| Espaço                 | Tela e estado                                                                                            | Tamanho                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------- |
| `cameraButtonEnabled`  | Câmera — disparo, normal. Aplicado como imagem de fundo.                                                 | 70 × 70                     |
| `cameraButtonDisabled` | Câmera — disparo, desativado.                                                                            | 70 × 70                     |
| `cameraButtonPressed`  | Câmera — disparo, destacado.                                                                             | 70 × 70                     |
| `closeButtonEnabled`   | Câmera — fechar redondo, normal. Imagem de fundo.                                                        | 40 × 40                     |
| `closeButtonDisabled`  | Câmera — fechar redondo, desativado e destacado.                                                         | 40 × 40                     |
| `closeIcon`            | Glifo X na folha de ajuda, na folha de exclusão e na pré-visualização de upload.                         | 28 × 28 / 40 × 40 / 48 × 48 |
| `helpIcon`             | Câmera — botão de ajuda.                                                                                 | 40 × 40                     |
| `backArrow`            | Voltar nas telas Instruções, Método de validação, Pré-visualização, Revisão de upload e Falha no upload. | 40–44 pt                    |
| `eyeIcon`              | Revisão de upload — pré-visualização em um espaço de arquivo.                                            | 32 × 32                     |
| `trashIcon`            | Revisão de upload — excluir em um espaço de arquivo.                                                     | 32 × 32                     |
| `successIcon`          | Revisão de upload — marca de verificação em um espaço preenchido.                                        | 20 × 20                     |
| `alertIcon`            | Banner de erro da câmera e banner de aviso da revisão de upload.                                         | 24 × 24 / 20 × 20           |
| `failureIcon`          | Falha no upload — ícone grande de status.                                                                | 100 × 100                   |
| `validationTypeCamera` | Método de validação — “tirar uma foto”.                                                                  | 24 × 24                     |
| `validationTypeUpload` | Método de validação — “anexar um documento”.                                                             | 24 × 24                     |
| `cameraHelpHint1`      | Ajuda da câmera — primeira dica.                                                                         | 56 × 56                     |
| `cameraHelpHint2`      | Ajuda da câmera — segunda dica.                                                                          | 56 × 56                     |
| `cameraHelpHint3`      | Ajuda da câmera — terceira dica.                                                                         | 56 × 56                     |

### Sequências animadas

Todos os 5 espaços são `string[]` — um array ordenado de URIs de frames. Elas controlam o carrossel de instruções, disposto com altura de 200 pt e no máximo 70% da largura do conteúdo.

| Espaço                 | Tela                             |
| ---------------------- | -------------------------------- |
| `captureInstructions1` | Instruções — página 1 da captura |
| `captureInstructions2` | Instruções — página 2 da captura |
| `captureInstructions3` | Instruções — página 3 da captura |
| `uploadInstructions1`  | Instruções — página 1 do upload  |
| `uploadInstructions2`  | Instruções — página 2 do upload  |

Uma única imagem é renderizada estática. Duas ou mais fazem crossfade, mantendo cada frame por cerca de 0,6 s com um fade de 0,3 s.

### Dimensionamento e renderização

As imagens personalizadas únicas nunca recebem tintura. As substituições são aplicadas como arte original, então os tokens de cor do SDK não podem recolorí-las. Forneça imagens já na cor desejada. Os assets empacotados mantêm sua tintura existente.

Os botões de disparo e de fechar da câmera se esticam para preencher. Forneça um gráfico quadrado com a forma circular já desenhada nele.

Outros ícones de botão (`helpIcon`, `backArrow`, `eyeIcon`, `trashIcon`, e `closeIcon` nas folhas de ajuda e exclusão) são renderizados em seu próprio tamanho — forneça-os no tamanho da tabela. `closeIcon` na pré-visualização de upload é esticado para preencher seu botão de 48 × 48.

Cada slot restante é dimensionado para caber e recebe barras letterbox dentro do contêiner.

Forneça `@2x` e `@3x` (ou densidades Metro equivalentes). O SDK não faz nenhum tratamento extra de DPI na URI que você passar.

O modo escuro não é resolvido por aparência. Qualquer URI que você passar é usada no claro e no escuro. Se você precisar de alternância, escolha a URI em JS a partir de `useColorScheme()` antes de chamar `open()`.

As animações respeitam a Redução de Movimento. Quando a configuração do sistema está ativada, uma sequência renderiza apenas seu primeiro quadro.

### Exemplos

#### Personalização completa

```typescript
import { Image } from 'react-native';
import {
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const uri = (mod: number) => Image.resolveAssetSource(mod).uri;

const frames = (...mods: number[]) => mods.map((m) => Image.resolveAssetSource(m).uri);

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [
    CerttaAcceptedDocumentType.IDENTITY_CARD,
    CerttaAcceptedDocumentType.DRIVER_LICENSE,
  ],
  imageCustomization: {
    cameraButtonEnabled: uri(require('./assets/brand_shutter.png')),
    cameraButtonDisabled: uri(require('./assets/brand_shutter_disabled.png')),
    cameraButtonPressed: uri(require('./assets/brand_shutter_pressed.png')),
    closeButtonEnabled: uri(require('./assets/brand_close_button.png')),
    closeButtonDisabled: uri(require('./assets/brand_close_button_disabled.png')),
    closeIcon: uri(require('./assets/brand_close_glyph.png')),
    helpIcon: uri(require('./assets/brand_help.png')),
    backArrow: uri(require('./assets/brand_back.png')),
    eyeIcon: uri(require('./assets/brand_preview.png')),
    trashIcon: uri(require('./assets/brand_delete.png')),
    successIcon: uri(require('./assets/brand_success.png')),
    alertIcon: uri(require('./assets/brand_alert.png')),
    failureIcon: uri(require('./assets/brand_failure.png')),
    validationTypeCamera: uri(require('./assets/brand_camera.png')),
    validationTypeUpload: uri(require('./assets/brand_upload.png')),
    cameraHelpHint1: uri(require('./assets/brand_hint_frame.png')),
    cameraHelpHint2: uri(require('./assets/brand_hint_glare.png')),
    cameraHelpHint3: uri(require('./assets/brand_hint_legible.png')),
    captureInstructions1: frames(
      require('./assets/brand_capture_1_1.png'),
      require('./assets/brand_capture_1_2.png'),
      require('./assets/brand_capture_1_3.png'),
    ),
    captureInstructions2: frames(
      require('./assets/brand_capture_2_1.png'),
      require('./assets/brand_capture_2_2.png'),
    ),
    captureInstructions3: frames(
      require('./assets/brand_capture_3_1.png'),
      require('./assets/brand_capture_3_2.png'),
    ),
    uploadInstructions1: frames(
      require('./assets/brand_upload_1_1.png'),
      require('./assets/brand_upload_1_2.png'),
    ),
    uploadInstructions2: frames(
      require('./assets/brand_upload_2_1.png'),
      require('./assets/brand_upload_2_2.png'),
    ),
  },
};

await open(config);
```

Ajuste os `uri` / `frames` funções auxiliares para corresponder à forma como você escreve `require()` no seu projeto; o importante é passar `.uri` (e um array de URIs para sequências).

#### Personalização parcial

```typescript
const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  imageCustomization: {
    helpIcon: Image.resolveAssetSource(require('./assets/brand_help.png')).uri,
    failureIcon: Image.resolveAssetSource(require('./assets/brand_failure.png')).uri,
  },
};

await open(config);
```

#### Combinando com cores

Os dois campos são independentes na mesma configuração. As cores são aplicadas no iOS via TypeScript; no Android, ainda são usados `colors.xml`.

```typescript
const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  colorCustomization: {
    accent: '#1B5E20',
  },
  imageCustomization: {
    helpIcon: Image.resolveAssetSource(require('./assets/brand_help.png')).uri,
  },
};

await open(config);
```

### Comportamento

Somente os slots que você definir são aplicados — todo slot omitido mantém seu asset empacotado.

As imagens são limitadas ao fluxo. Elas são aplicadas quando ele começa e liberadas quando ele termina.

Cada sessão substitui as imagens da sessão anterior como um todo, em vez de mesclá-las.

### O que não pode ser personalizado

* As animações na câmera — a virada do documento e a animação de sucesso do carregamento. Elas controlam o comportamento da captura, em vez da arte das instruções.
* O chevron em um cartão de método de validação.
* O ícone em um slot de upload vazio.
* O botão de fechar no banner de erro na câmera. `closeIcon` não o cobre.
* O formato de botões, cards e sheets — o raio dos cantos, o traço e o estilo da borda são fixos. Para alterar a forma de um botão de disparo ou de um botão circular de fechar, desenhe isso na imagem que você fornecer para esse slot.

O texto é personalizado separadamente — veja Personalização de Texto. Cores — veja Personalização de Cores.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-imagens.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.
