Customização

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

interface FaceTecOptionsInput {
  locale?: 'pt-BR' | 'en-US';
  strings?: I18nStrings;
  customization?: FaceTecCustomizationOptions;
  lowLightCustomization?: FaceTecCustomizationOptions;
  dynamicDimmingCustomization?: FaceTecCustomizationOptions;
  configuration?: FaceTecConfigurationOptions;
}

await sdk.run({
  onInit,
  options: {
    locale: 'pt-BR',
    customization: {
      primaryColor: '#B72819',
    },
  },
});

locale/strings — idioma e textos. Veja Locale e textos.
customization — tema visual aplicado em qualquer condição de luz. Veja 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.
configuration — comportamento não-visual (áudio, watermark, logging). Veja Configuração de comportamento.

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.

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.

options: {
  locale: 'en-US',
}

Use strings para sobrescrever qualquer subconjunto dos textos — o SDK faz merge com o default do locale.

options: {
  locale: 'pt-BR',
  strings: {
    feedback: { centerFace: 'Coloque o rosto no centro' },
  },
}

Todas as chaves, organizadas por tela e com o texto padrão de cada uma, estão em Textos e áudios.

Customização visual

Atalho `primaryColor`

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.

oval — traço e progresso do oval de captura

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)
}

frame — moldura ao redor da câmera

interface FrameCustomization {
  borderColor?: string;        // cor da borda
  backgroundColor?: string;    // cor de fundo
  borderCornerRadius?: string; // raio da borda, em pixels — ex: '24'
}

overlay — camada atrás da câmera

interface OverlayCustomization {
  backgroundColor?: string;    // cor do overlay
  showBrandingImage?: boolean; // true = exibe brandingImage, false = oculta
  brandingImage?: string;      // URL ou data URI (base64) da logo
}

guidance — telas de instrução (antes da captura)

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
}

resultScreen — tela final (sucesso/falha)

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
}

feedback — barra de feedback durante a captura

interface FeedbackCustomization {
  backgroundColor?: string;
  textColor?: string;
  textFont?: string; // nome da fonte
}

cancelButton — botão de cancelar

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
}

initialLoadingAnimation — animação de carregamento inicial

interface InitialLoadingAnimationCustomization {
  backgroundColor?: string;
  foregroundColor?: string;
}

enterFullScreen — tela de 'entrar em tela cheia' (só dentro de iframe)

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.

exitAnimation — animação ao fechar a captura

interface ExitAnimationCustomization {
  success?: 'none' | 'rippleOut' | 'fadeOutMin';
  unsuccess?: 'none' | 'rippleOut' | 'fadeOutMin';
}

orientationScreen — aviso de orientação incorreta (mobile)

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.

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.

options: {
  customization: { primaryColor: '#B72819' },
  lowLightCustomization: {
    overlay: { backgroundColor: '#000000CC' },
  },
}

Configuração de comportamento

options.configuration controla comportamento não-visual:

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'
}

options: {
  configuration: {
    vocalGuidance: { mode: 'minimal' },
    faceTecLoggingMode: 'localhostOnly',
  },
}

Para usar gravações próprias na narração, veja Áudios.

Próximos passos

Implementação

Configuração completa e fluxo de captura

Solução de problemas

Mapeamento de erros e diagnóstico

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

API resumida

Locale e textos

Customização visual

Atalho `primaryColor`

Grupos de customização

Estados de iluminação

Configuração de comportamento

Próximos passos

Implementação

Solução de problemas

​API resumida

​Locale e textos

​Customização visual

​Atalho primaryColor

​Grupos de customização

​Estados de iluminação

​Configuração de comportamento

​Próximos passos

Implementação

Solução de problemas

API resumida

Locale e textos

Customização visual

Atalho `primaryColor`

Grupos de customização

Estados de iluminação

Configuração de comportamento

Próximos passos