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

> Como personalizar idiomas, textos e cores do Valid Liveness SDK

O SDK permite personalização completa através do objeto `hubOptions`.

## Idiomas Suportados

```javascript theme={"theme":"catppuccin-latte"}
const hubOptions = {
  locale: 'pt-BR', // 'pt-BR' | 'en-US' | 'custom'
};
```

| Valor    | Descrição                   |
| -------- | --------------------------- |
| `pt-BR`  | Português (Brasil) — padrão |
| `en-US`  | Inglês (Estados Unidos)     |
| `custom` | Textos personalizados       |

## Personalização de Textos

Você pode customizar todos os textos exibidos na interface usando `locale: 'custom'`:

<Tabs>
  <Tab title="Ações e Acessibilidade">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      locale: 'custom',
      strings: {
        actions: {
          ready: 'ESTOU PRONTO',
          tryAgain: 'TENTE NOVAMENTE',
        },
        accessibility: {
          cancelButton: 'Cancelar',
          tapGuidance: 'Toque duas vezes na tela para orientação',
        },
        instructions: {
          title: 'Verificação Facial',
          subtitle: 'Posicione seu rosto no círculo e pressione Estou Pronto',
        },
      },
    };
    ```
  </Tab>

  <Tab title="Feedback">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      locale: 'custom',
      strings: {
        feedback: {
          centerFace: 'Centralize Seu Rosto',
          faceNotFound: 'Rosto Não Encontrado',
          moveCloser: 'Aproxime-se',
          moveBack: 'Afaste-se',
          moveLeft: 'Mova Para a Esquerda',
          moveRight: 'Mova Para a Direita',
          moveUp: 'Mova Para Cima',
          moveDown: 'Mova Para Baixo',
          moveToEyeLevel: 'Posicione na Altura dos Olhos',
          lookStraightAhead: 'Olhe Para Frente',
          faceNotUpright: 'Mantenha a Cabeça Reta',
          keepHeadStraight: 'Mantenha a Cabeça Reta',
          holdStill: 'Mantenha-se Parado',
          useEvenLighting: 'Ilumine o Rosto Uniformemente',
          tooBlurry: 'Muito Embaçado',
          multipleFacesDetected: 'Múltiplos Rostos Detectados',
          onlyOneFaceAllowed: 'Apenas Um Rosto Permitido',
          perfect: 'Perfeito!',
          readyToCapture: 'Pronto Para Capturar',
        },
      },
    };
    ```
  </Tab>

  <Tab title="Status e Retry">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      locale: 'custom',
      strings: {
        status: {
          loading: 'Carregando...',
          processing: 'Analisando biometria facial...',
          uploading: 'Enviando...',
          analyzing: 'Analisando...',
          initializing: 'Inicializando...',
          connectingCamera: 'Conectando à Câmera...',
          success: 'Sucesso',
          captureComplete: 'Captura Concluída',
          verificationComplete: 'Verificação Concluída',
        },
        retry: {
          title: 'Tentar Novamente',
          subtitle: 'Faça uma Captura Melhor',
          yourImageLabel: 'Sua Foto',
          idealImageLabel: 'Pose Ideal',
          instructionBetterLighting: 'Use Melhor Iluminação',
          instructionNeutralExpression: 'Expressão Neutra, Sem Sorriso',
          instructionCleanCamera: 'Limpe a Lente da Câmera',
          instructionBetterPosition: 'Melhore o Posicionamento',
        },
      },
    };
    ```
  </Tab>

  <Tab title="Erros">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      locale: 'custom',
      strings: {
        errors: {
          cameraPermissionDenied: 'Permissão de Câmera Negada',
          cameraNotFound: 'Câmera Não Encontrada',
          cameraInUse: 'Câmera em Uso',
          networkError: 'Erro de Conexão',
          uploadFailed: 'Falha no Envio',
          sessionExpired: 'Sessão Expirada',
          sessionFailed: 'Falha na Sessão',
          faceNotDetected: 'Rosto Não Detectado',
          faceNotClear: 'Rosto Não Está Claro',
          multipleFaces: 'Múltiplos Rostos Detectados',
          unexpectedError: 'Erro Inesperado',
          tryAgainLater: 'Tente Novamente Mais Tarde',
        },
      },
    };
    ```
  </Tab>
</Tabs>

<Tip>
  Os valores acima são os **padrões do idioma pt-BR**. Você pode combinar idioma
  predefinido com customização parcial — as strings não especificadas usarão os
  valores padrão do idioma selecionado.
</Tip>

## Personalização de Cores (Tema)

Customize a aparência visual da interface:

<Tabs>
  <Tab title="Cores Principais">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      colorTheme: {
        // Cores principais
        primaryColor: '#667eea',       // Cor da marca principal
        secondaryColor: '#764ba2',     // Cor de destaque

        // Fundos
        backgroundColor: '#ffffff',    // Fundo principal
        surfaceColor: '#f8f9fa',       // Fundo de cards e painéis
        overlayColor: 'rgba(0, 0, 0, 0.6)', // Sobreposição de modal
      },
    };
    ```
  </Tab>

  <Tab title="Textos e Botões">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      colorTheme: {
        // Textos
        textColor: '#333333',          // Texto principal
        textColorSecondary: '#666666', // Texto secundário
        textColorLight: '#ffffff',     // Texto claro (em fundos escuros)

        // Botões
        buttonColor: '#667eea',        // Fundo do botão principal
        confirmButtonColor: '#5FCC17', // Botão de confirmar
        cancelButtonColor: '#FF453A',  // Botão de cancelar
        buttonTextColor: '#ffffff',    // Texto dos botões
        buttonHoverColor: '#5a67d8',   // Hover do botão
        buttonDisabledColor: '#e2e8f0', // Botão desabilitado
      },
    };
    ```
  </Tab>

  <Tab title="Estados e Elementos">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      colorTheme: {
        // Estados
        successColor: '#5FCC17',       // Sucesso
        errorColor: '#f56565',         // Erro
        warningColor: '#ed8936',       // Aviso
        infoColor: '#4299e1',          // Informação

        // Elementos da face
        frameColor: '#ffffff',         // Moldura de detecção facial
        progressColor1: '#667eea',     // Cor do progresso
        progressColor2: '#764ba2',     // Cor secundária do progresso
        maskColor: 'rgba(0, 0, 0, 0.6)', // Máscara de sobreposição

        // Loading
        loadingColor: '#ffffff',       // Indicador de carregamento

        // Branding
        brandingImage: 'https://sua-empresa.com/logo.png', // Logo (URL ou base64)
      },
    };
    ```
  </Tab>
</Tabs>

### Propriedade `brandingImage`

A propriedade `brandingImage` permite exibir o logo da sua marca na interface do SDK. Aceita:

* **URL**: link para uma imagem (PNG, SVG, etc.)
* **Base64**: string data URI com a imagem codificada

## Temas Pré-definidos

O SDK exporta dois temas prontos para uso:

### `VALID_COLOR_THEME` — Tema da Valid

Tema preto e branco com a identidade visual da Valid:

```javascript theme={"theme":"catppuccin-latte"}
const hubOptions = {
  colorTheme: ValidHub.VALID_COLOR_THEME,
};
```

### `DEFAULT_COLOR_THEME` — Tema Padrão

Tema neutro com tons de azul/roxo (usado quando nenhum tema é especificado):

```javascript theme={"theme":"catppuccin-latte"}
const hubOptions = {
  colorTheme: ValidHub.DEFAULT_COLOR_THEME,
};
```

### Logo da Valid

O SDK também exporta o logo da Valid em base64 para uso com o `brandingImage`:

```javascript theme={"theme":"catppuccin-latte"}
const hubOptions = {
  colorTheme: {
    ...ValidHub.VALID_COLOR_THEME,
    brandingImage: ValidHub.VALID_LOGO_BASE64,
  },
};
```

## Componentes de UI

Você pode controlar a visibilidade e o comportamento de componentes individuais da interface usando `UIComponentOptions`:

<AccordionGroup>
  <Accordion title="Título e Subtítulo">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      uiComponents: {
        title: {
          enabled: true,
          text: 'Verificação Facial',
        },
        subtitle: {
          enabled: true,
          text: 'Posicione seu rosto no círculo',
        },
      },
    };
    ```
  </Accordion>

  <Accordion title="Botões (captura, confirmar, cancelar)">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      uiComponents: {
        captureButton: {
          enabled: true,
          position: 'bottom',   // 'bottom' | 'right' | 'left'
          size: 'medium',        // 'small' | 'medium' | 'large'
        },
        confirmButton: {
          enabled: true,
        },
        cancelButton: {
          enabled: true,
          position: 'topRight', // 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'disabled'
        },
        switchCameraButton: {
          enabled: true,
        },
        backButton: {
          enabled: true,
        },
      },
    };
    ```
  </Accordion>

  <Accordion title="Máscara de Detecção Facial">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      uiComponents: {
        faceDetectionMask: {
          enabled: true,
          type: 'oval',        // 'face' | 'square' | 'circle' | 'oval'
          strokeWidth: 2,
          showProgress: true,
        },
      },
    };
    ```
  </Accordion>

  <Accordion title="Loading e Feedback">
    ```javascript theme={"theme":"catppuccin-latte"}
    const hubOptions = {
      uiComponents: {
        loadingIndicator: {
          enabled: true,
          type: 'dots',        // 'dots' | 'spinner' | 'progress'
        },
        feedbackDisplay: {
          enabled: true,
          position: 'bottom',  // 'top' | 'center' | 'bottom'
          showIcon: true,
        },
      },
    };
    ```
  </Accordion>
</AccordionGroup>

## Exemplos de Temas

<CodeGroup>
  ```javascript Tema Escuro theme={"theme":"catppuccin-latte"}
  const hubOptions = {
    locale: 'pt-BR',
    colorTheme: {
      primaryColor: '#818cf8',
      secondaryColor: '#a78bfa',
      backgroundColor: '#1f2937',
      surfaceColor: '#374151',
      overlayColor: 'rgba(0, 0, 0, 0.8)',
      textColor: '#f9fafb',
      textColorSecondary: '#d1d5db',
      textColorLight: '#f9fafb',
      buttonColor: '#818cf8',
      confirmButtonColor: '#34d399',
      cancelButtonColor: '#f87171',
      buttonTextColor: '#1f2937',
      successColor: '#34d399',
      errorColor: '#f87171',
      warningColor: '#fbbf24',
      infoColor: '#60a5fa',
      frameColor: '#818cf8',
      maskColor: 'rgba(0, 0, 0, 0.7)',
    },
  };
  ```

  ```javascript Tema Claro Personalizado theme={"theme":"catppuccin-latte"}
  const hubOptions = {
    locale: 'pt-BR',
    strings: {
      instructions: {
        title: 'Verificação de Identidade',
        subtitle: 'Olhe diretamente para a câmera',
      },
      actions: {
        ready: 'COMEÇAR',
      },
    },
    colorTheme: {
      primaryColor: '#003366',
      secondaryColor: '#0066cc',
      backgroundColor: '#f5f5f5',
      buttonColor: '#003366',
      confirmButtonColor: '#28a745',
      frameColor: '#003366',
    },
  };
  ```
</CodeGroup>

## Exemplo Completo com Personalização

```javascript theme={"theme":"catppuccin-latte"}
const hub = ValidHub.createHub();

const config = {
  apiKey: 'sua-api-key',
  cek: 'sua-cek-base64',
  mount: '#camera-container',
  env: 'production',
  appName: 'minha-aplicacao',
  risk: 'LIVENESS_RISK_HIGH',

  hubOptions: {
    locale: 'pt-BR',
    strings: {
      instructions: {
        title: 'Verificação de Identidade',
        subtitle: 'Posicione seu rosto no centro da tela',
      },
      actions: {
        ready: 'ESTOU PRONTO',
        tryAgain: 'TENTE NOVAMENTE',
      },
      feedback: {
        centerFace: 'Centralize Seu Rosto',
        faceNotFound: 'Rosto Não Encontrado',
        perfect: 'Perfeito!',
        holdStill: 'Mantenha-se Parado',
      },
      status: {
        processing: 'Analisando biometria facial...',
        success: 'Sucesso',
      },
    },
    colorTheme: {
      ...ValidHub.VALID_COLOR_THEME,
      brandingImage: ValidHub.VALID_LOGO_BASE64,
    },
  },

  onSuccess: (result) => {
    console.log('Sucesso:', result);
  },
  onFailure: (error) => {
    console.error('Erro:', error);
  },
  onProgress: (state) => {
    console.log('Estado:', state);
  },
};

const result = await hub.run(config);
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" href="/plataforma/liveness/hub/sdk/web/implementation">
    Veja como implementar a verificação
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/plataforma/liveness/hub/sdk/web/troubleshooting">
    Tratamento de erros e boas práticas
  </Card>
</CardGroup>