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

> Personalize idioma, textos e tema visual da UI do LivenessFacetecSDK Web v10

A personalização da UI do FaceTec Web v10 é feita pelo campo `options` da configuração do `sdk.run()`. Diferente da v9, o sistema de tema não usa mais uma paleta fixa (`colorTheme`) — os campos de customização espelham 1:1 os próprios grupos de UI do FaceTec, dando controle bem mais granular.

Sem `options.customization`, a UI renderiza 100% no visual padrão do FaceTec.

## API resumida

```typescript theme={"theme":"catppuccin-latte"}
interface FaceTecOptionsInput {
  locale?: 'pt-BR' | 'en-US';
  strings?: I18nStrings;
  customization?: FaceTecCustomizationOptions;
  lowLightCustomization?: FaceTecCustomizationOptions;
  dynamicDimmingCustomization?: FaceTecCustomizationOptions;
  configuration?: FaceTecConfigurationOptions;
}
```

```javascript theme={"theme":"catppuccin-latte"}
await sdk.run({
  onInit,
  options: {
    locale: 'pt-BR',
    customization: {
      primaryColor: '#B72819',
    },
  },
});
```

* `locale`/`strings` — idioma e textos. Veja [Locale e textos](#locale-e-textos).
* `customization` — tema visual aplicado em qualquer condição de luz. Veja [Customização visual](#customização-visual).
* `lowLightCustomization`/`dynamicDimmingCustomization` — sobrescritas aplicadas por cima de `customization`, apenas nos estados de pouca luz ou de tela-como-flash. Veja [Estados de iluminação](#estados-de-iluminação).
* `configuration` — comportamento não-visual (áudio, watermark, logging). Veja [Configuração de comportamento](#configuração-de-comportamento).

<Info>
  A customização e a localização são reaplicadas a cada chamada de `sdk.run()`, mesmo reaproveitando a mesma instância do SDK — você pode passar opções diferentes em tentativas diferentes.
</Info>

## Locale e textos

Apenas `pt-BR` (default) e `en-US` são suportados, ambos com textos padrão já embutidos no bundle — não há carregamento externo.

```javascript theme={"theme":"catppuccin-latte"}
options: {
  locale: 'en-US',
}
```

Use `strings` para sobrescrever qualquer subconjunto dos textos — o SDK faz merge com o default do `locale`. Os grupos disponíveis em `I18nStrings` são: `actions`, `accessibility` (textos de leitor de tela, podem divergir dos textos visuais), `presession`, `feedback`, `instructions`, `retry`, `cameraIssue`, `cameraPermission`, `fullscreen`, `orientation`, `status`, `result`.

```javascript theme={"theme":"catppuccin-latte"}
options: {
  locale: 'pt-BR',
  strings: {
    instructions: { title: 'Verificação Valid' },
  },
}
```

## Customização visual

### Atalho `primaryColor`

```javascript theme={"theme":"catppuccin-latte"}
options: {
  customization: {
    primaryColor: '#B72819',
  },
}
```

`primaryColor` propaga automaticamente uma cor de destaque para o traço/progresso do oval, borda do frame, botão primário (com tons derivados de hover/desabilitado), texto do botão, barra de feedback e tela de resultado — sem nunca alterar nenhum plano de fundo. Qualquer campo explícito dos grupos abaixo sempre tem prioridade sobre o que o atalho geraria.

### Grupos de customização

Cada grupo abaixo corresponde a um elemento da UI do FaceTec e vai dentro de `options.customization`. Sobrescreva só os campos que precisar — o restante do grupo cai no default do FaceTec. **Todo campo de cor espera uma string hex** (ex.: `'#B72819'`); campos de imagem esperam uma URL ou `data:` URI (base64); campos de fonte esperam o nome da fonte como string.

<AccordionGroup>
  <Accordion title="oval — traço e progresso do oval de captura">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface OvalCustomization {
      strokeColor?: string;      // cor do traço do oval
      progressColor1?: string;   // cor do arco de progresso (início)
      progressColor2?: string;   // cor do arco de progresso (fim)
    }
    ```
  </Accordion>

  <Accordion title="frame — moldura ao redor da câmera">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface FrameCustomization {
      borderColor?: string;        // cor da borda
      backgroundColor?: string;    // cor de fundo
      borderCornerRadius?: string; // raio da borda, em pixels — ex: '24'
    }
    ```
  </Accordion>

  <Accordion title="overlay — camada atrás da câmera">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface OverlayCustomization {
      backgroundColor?: string;    // cor do overlay
      showBrandingImage?: boolean; // true = exibe brandingImage, false = oculta
      brandingImage?: string;      // URL ou data URI (base64) da logo
    }
    ```
  </Accordion>

  <Accordion title="guidance — telas de instrução (antes da captura)">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface GuidanceCustomization {
      backgroundColors?: string;               // cor de fundo da tela
      foregroundColor?: string;                // cor de texto/ícones
      buttonBackgroundNormalColor?: string;
      buttonBackgroundHighlightColor?: string;
      buttonBackgroundDisabledColor?: string;
      buttonTextNormalColor?: string;
      buttonTextHighlightColor?: string;
      buttonTextDisabledColor?: string;
      readyScreenOvalFillColor?: string;       // cor do oval na tela "pronto para começar"
      readyScreenTextBackgroundColor?: string;
      retryScreenImageBorderColor?: string;
      retryScreenOvalStrokeColor?: string;
      retryScreenIdealImage?: string;          // URL/data URI da imagem de referência no retry
      cameraPermissionsScreenImage?: string;   // URL/data URI na tela de permissão de câmera
      cameraFeedIssueScreenImage?: string;     // URL/data URI na tela de problema de câmera
      headerFont?: string;                     // nome da fonte do título
      subtextFont?: string;                    // nome da fonte do texto secundário
      buttonFont?: string;                     // nome da fonte dos botões
    }
    ```
  </Accordion>

  <Accordion title="resultScreen — tela final (sucesso/falha)">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface ResultScreenCustomization {
      backgroundColors?: string;
      foregroundColor?: string;
      resultAnimationBackgroundColor?: string;
      resultAnimationForegroundColor?: string;
      resultAnimationUnsuccessBackgroundColor?: string;
      resultAnimationUnsuccessForegroundColor?: string;
      uploadProgressFillColor?: string;
      activityIndicatorColor?: string;
      messageFont?: string; // nome da fonte da mensagem de resultado
    }
    ```
  </Accordion>

  <Accordion title="feedback — barra de feedback durante a captura">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface FeedbackCustomization {
      backgroundColor?: string;
      textColor?: string;
      textFont?: string; // nome da fonte
    }
    ```
  </Accordion>

  <Accordion title="cancelButton — botão de cancelar">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface CancelButtonCustomization {
      location?: 'topLeft' | 'topRight' | 'disabled' | 'custom';
      // obrigatório quando location === 'custom':
      customLocation?: { x: number; y: number; width: number; height: number };
      customImage?: string;               // URL/data URI do ícone customizado
      hideForCameraPermissions?: boolean;  // oculta o botão na tela de permissão de câmera
    }
    ```
  </Accordion>

  <Accordion title="initialLoadingAnimation — animação de carregamento inicial">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface InitialLoadingAnimationCustomization {
      backgroundColor?: string;
      foregroundColor?: string;
    }
    ```
  </Accordion>

  <Accordion title="enterFullScreen — tela de 'entrar em tela cheia' (só dentro de iframe)">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface EnterFullScreenCustomization {
      backgroundColors?: string;
      foregroundColor?: string;
      buttonBackgroundNormalColor?: string;
      buttonBackgroundHighlightColor?: string;
      buttonBackgroundDisabledColor?: string;
      buttonTextNormalColor?: string;
      buttonTextHighlightColor?: string;
      buttonTextDisabledColor?: string;
      enterFullScreenImage?: string; // URL/data URI
      headerFont?: string;
      subtextFont?: string;
      buttonFont?: string;
    }
    ```

    Só é exibida quando o FaceTec roda dentro de um `iframe`.
  </Accordion>

  <Accordion title="exitAnimation — animação ao fechar a captura">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface ExitAnimationCustomization {
      success?: 'none' | 'rippleOut' | 'fadeOutMin';
      unsuccess?: 'none' | 'rippleOut' | 'fadeOutMin';
    }
    ```
  </Accordion>

  <Accordion title="orientationScreen — aviso de orientação incorreta (mobile)">
    ```typescript theme={"theme":"catppuccin-latte"}
    interface OrientationScreenCustomization {
      backgroundColors?: string;
      foregroundColor?: string;
      iconImage?: string; // URL/data URI
      messageFont?: string;
    }
    ```

    Exibida em dispositivos móveis quando o usuário rotaciona para uma orientação não suportada.
  </Accordion>
</AccordionGroup>

```javascript theme={"theme":"catppuccin-latte"}
options: {
  customization: {
    primaryColor: '#B72819',
    frame: {
      borderCornerRadius: '24',
    },
    cancelButton: {
      location: 'topRight',
    },
  },
}
```

## Estados de iluminação

`lowLightCustomization` e `dynamicDimmingCustomization` aceitam exatamente os mesmos grupos de `customization` (acima), mas são aplicados apenas quando o FaceTec detecta pouca luz ou usa a própria tela como flash — o resultado final é um merge por cima da customização base.

```javascript theme={"theme":"catppuccin-latte"}
options: {
  customization: { primaryColor: '#B72819' },
  lowLightCustomization: {
    overlay: { backgroundColor: '#000000CC' },
  },
}
```

## Configuração de comportamento

`options.configuration` controla comportamento não-visual:

```typescript theme={"theme":"catppuccin-latte"}
interface FaceTecConfigurationOptions {
  vocalGuidance?: {
    mode?: 'full' | 'minimal' | 'disabled'; // default: 'disabled'
    // URLs de áudio próprio substituindo a narração padrão do FaceTec em cada etapa:
    frameYourFaceSoundFile?: string;
    moveCloserSoundFile?: string;
    retrySoundFile?: string;
    uploadingSoundFile?: string;
    successSoundFile?: string;
    pressButtonToStartSoundFile?: string;
  };
  securityWatermarkImage?: 'faceTecZoOm' | 'faceTec' | 'faceTecPoweredBy';
  enableCameraPermissionsHelpScreen?: boolean;  // tela de ajuda quando a câmera é negada
  shouldDrawOvalStrokeOpaque?: boolean;         // opacidade do traço do oval
  enableClickableReadyScreenSubtext?: boolean;  // torna clicável o subtexto da tela inicial
  enableDevelopmentModeTag?: boolean;           // exibe uma tag de "ambiente de desenvolvimento"
  faceTecLoggingMode?: 'default' | 'localhostOnly'; // log interno do motor FaceTec — default: 'localhostOnly'
}
```

```javascript theme={"theme":"catppuccin-latte"}
options: {
  configuration: {
    vocalGuidance: { mode: 'minimal' },
    faceTecLoggingMode: 'localhostOnly',
  },
}
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/implementacao">
    Configuração completa e fluxo de captura
  </Card>

  <Card title="Solução de problemas" icon="wrench" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/troubleshooting">
    Mapeamento de erros e diagnóstico
  </Card>
</CardGroup>