> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Customização

> Configure idioma, segurança, captura e visual do LivenessIdentySDK Web

A configuração do `LivenessIdentySDK` Web é feita pelo campo `options` do `sdk.run()`. Todas as opções são opcionais: sem nenhuma, o SDK já usa as configurações recomendadas.

```javascript theme={"theme":"catppuccin-latte"}
await sdk.run({
  onInit,
  options: {
    locale: 'pt-BR',
    showCaptureTraining: false,
    appUI: 'TICKING',
  },
});
```

## Idioma e textos

| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `locale` | `'pt-BR' \| 'en-US'` | `pt-BR` | Idioma das mensagens durante a captura. |
| `strings` | `Record<string, string>` | — | Substitui textos por chave, por cima do `locale`. Ex.: `{ FEEDBACK_NOT_CENTERED: 'Centralize o rosto' }`. Todas as chaves estão em [Textos](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/textos.md). |

> [!NOTE]
>
> A tela de instruções é uma imagem com texto em inglês. Para trocá-la, use [`graphics.FACE_TRAINING`](#visual) ou pule-a com `showCaptureTraining: false`.

## Segurança

| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `enableAS` | boolean | `true` | Liga a prova de vida. **Não recomendamos desligar:** com `false` a captura não é verificada como pessoa real. |
| `asThreshold` | nível | `VERY_HIGH` | Rigor da prova de vida. Mais alto = mais seguro, com mais reprovações de usuários legítimos. |
| `enableDF` | boolean | `true` | Detecção de **deepfake** e de **câmera virtual**. Aumenta o tempo de análise em cerca de 2 s. |
| `dfThreshold` | nível | `BALANCED_VERY_HIGH` | Rigor da detecção de deepfake. |

Níveis, do mais rigoroso ao mais permissivo: `HIGHEST`, `VERY_HIGH`, `BALANCED_VERY_HIGH`, `HIGH`, `BALANCED_HIGH`, `MODERATE`, `MEDIUM`, `LOW`.

> [!WARNING]
>
> Câmera virtual e deepfake **só são detectados com `enableDF: true`**. Recomendamos não desligar.

## Captura

| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `showCaptureTraining` | boolean | `true` | Tela de instruções antes da câmera. `false` vai direto à câmera. |
| `captureTimeout` | number (ms) | `30000` | Tempo para capturar o rosto, de 30 000 a 50 000. Esgotado → `CAPTURE_TIMEOUT`. |
| `enableRetakeScreen` | boolean | `false` | Ao esgotar o tempo, mostra uma tela "tentar de novo" que reabre a câmera na mesma sessão. "Fechar" → `CAPTURE_TIMEOUT`. |
| `allowClose` | boolean | `true` | Mostra o botão de fechar a tela de captura (fechar → `USER_CANCELLED`). |
| `assisted` | boolean | `false` | Usa a câmera **traseira**, para quando outra pessoa filma o usuário. |
| `requiredTemplates` | `('PNG' \| 'ISO_19794_5' \| 'ISO_39794_5')[]` | — | Formatos extras da imagem, devolvidos em `result.templates`. O JPEG (`result.image`) vem sempre. |
| `enableICAOChecks` | boolean | `false` | Mede a conformidade da foto com o padrão **ICAO** (fotos de passaporte e documentos de viagem). Devolve `result.icao` e `result.iso` — veja [ICAO e ISO](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md#icao-e-iso). Não altera o resultado da verificação. |

## Checagens antes da captura

Peça para o usuário tirar óculos, chapéu, máscara ou a mão do rosto, ou manter os olhos abertos e a boca fechada, antes de a foto ser tirada.

| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `precaptureCheck` | boolean | `false` | Liga as checagens. Sem ele, `precaptureOptions` não tem efeito. |
| `precaptureOptions` | objeto de booleanos | — | Quais checagens ligar. Só as marcadas com `true` ficam ativas. |

| Checagem | Pede para o usuário | Texto exibido |
| - | - | - |
| `GLASSES` | Tirar os óculos | `FEEDBACK_REMOVE_GLASSES` |
| `SUNGLASSES` | Tirar os óculos escuros | `FEEDBACK_REMOVE_SUNGLASSES` |
| `HAT` | Tirar chapéu ou boné | `FEEDBACK_REMOVE_HAT` |
| `MASK` | Tirar a máscara | `FEEDBACK_REMOVE_MASK` |
| `HAND` | Tirar a mão do rosto | `FEEDBACK_REMOVE_HAND` |
| `EYE_OPENNESS` | Abrir os olhos | `FEEDBACK_OPEN_EYES` |
| `MOUTH_CLOSURE` | Fechar a boca | `FEEDBACK_CLOSE_MOUTH` |

```javascript theme={"theme":"catppuccin-latte"}
options: {
  precaptureCheck: true,
  precaptureOptions: {
    SUNGLASSES: true,
    HAT: true,
    MASK: true,
  },
}
```

Os textos de cada checagem podem ser trocados em [Textos](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/textos.md).

## Visual

| Opção | Tipo | Descrição |
| - | - | - |
| `appUI` | `'STANDARD' \| 'TICKING'` | `TICKING` mostra um anel de progresso em volta do oval. Padrão: `STANDARD`. |
| `graphics.canvas` | objeto de cores (CSS) | Cores da tela de captura — veja abaixo. |
| `graphics.FACE_TRAINING` | string (URL) | Imagem própria para a tela de instruções (ex.: uma arte em pt-BR). |

Cores de `graphics.canvas`:

| Chave | Onde |
| - | - |
| `canvasBackground` | Fundo em volta do oval |
| `canvasBackgroundAssisted` | Fundo no modo `assisted` |
| `labelBackground` | Faixa de mensagens |
| `ovalBorderBackground` / `ovalBorderErrorBackground` | Borda do oval: ok / com problema |
| `tickerDefaultBackground` / `tickerActiveBackground` | Anel de progresso, com `appUI: 'TICKING'` |

```javascript theme={"theme":"catppuccin-latte"}
options: {
  appUI: 'TICKING',
  graphics: {
    canvas: {
      canvasBackground: '#ffffff',
      labelBackground: '#00409E',
      ovalBorderBackground: '#00409E',
    },
  },
}
```

## Eventos

`options.events` traz avisos da tela de captura, para quem quer acompanhar a captura em detalhe. Não substituem `onProgress`, `onSuccess` e `onFailure`.

| Evento | Quando dispara |
| - | - |
| `onBusy()` | Ao preparar e abrir a câmera (várias vezes) |
| `onIdle()` | Uma vez, quando a câmera fica pronta |
| `onImageQualityDetected(quality)` | Logo antes da foto final, com `{ eyes_status, eyes_opening_grade, quality_metric, head_pose_check }` |
| `onCaptured(base64)` | Quando a foto é tirada — **antes** da análise |

```javascript theme={"theme":"catppuccin-latte"}
options: {
  events: {
    onImageQualityDetected: (q) => console.log('qualidade', q),
  },
}
```

> [!WARNING]
>
> A imagem de `onCaptured` ainda não foi validada. Use a imagem entregue em `onSuccess`.

## Próximos passos

> **[Implementação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md)**
>
> Configuração completa e fluxo de captura

> **[Solução de problemas](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/troubleshooting.md)**
>
> Mapeamento de erros e diagnóstico


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.