Customização

Personalize idioma, textos e cores da UI do LivenessFacetecSDK Web

A personalização da UI do FaceTec Web é feita pela classe HubOptions, passada no campo hubOptions da configuração do sdk.run(). Você pode trocar o idioma, sobrescrever qualquer texto e ajustar a paleta de cores.

API resumida

import type { HubOptions, ColorTheme, I18nStrings } from 'window.LivenessFacetecSDK';

new window.LivenessFacetecSDK.HubOptions({
  locale?: 'pt-BR' | 'en-US' | 'custom';
  strings?: Partial<I18nStrings>;
  colorTheme?: Partial<ColorTheme>;
});

• locale — escolhe o conjunto de textos padrão. Default pt-BR.
• strings — sobrescreve qualquer subconjunto dos textos. O SDK faz deep merge com o default do locale.
• colorTheme — sobrescreve qualquer subconjunto das cores. Também faz deep merge com o tema default.

const hubOptions = new window.LivenessFacetecSDK.HubOptions({
  locale: 'pt-BR',
  strings: {
    instructions: { title: 'Verificação Valid' },
  },
  colorTheme: {
    frameColor: '#B72819',
    successColor: '#16A34A',
  },
});

await sdk.run({
  mount: '#camera-container',
  env: 'production',
  onInit,
  hubOptions,
});

Locale

O SDK acompanha dois conjuntos de strings prontos:

Locale	Quando usar
'pt-BR' (default)	Aplicações em português brasileiro
'en-US'	Aplicações em inglês
'custom'	Quando você vai fornecer todas as strings em strings

const hubOptions = new window.LivenessFacetecSDK.HubOptions({ locale: 'en-US' });

Você pode misturar: escolher locale: 'pt-BR' e sobrescrever apenas os textos que precisam mudar.

Sobrescrita de textos

A interface I18nStrings agrupa os textos em onze categorias. Sobrescreva apenas o que precisar — o resto vem do locale.

interface I18nStrings {
  actions?: {
    ok?: string;
    ready?: string;
    tryAgain?: string;
    continue?: string;
  };
  accessibility?: {
    cancelButton?: string;
    tapGuidance?: string;
    keyDownGuidance?: string;
    movePhoneAway?: string;
    movePhoneCloser?: string;
    moveAwayWeb?: string;
    moveCloserWeb?: string;
    holdToEyeLevel?: string;
    holdToEyeLevelWeb?: string;
    faceTooFarLeft?: string;
    faceTooFarRight?: string;
    faceTooLow?: string;
    faceTooHigh?: string;
    faceRotatedTooFarLeft?: string;
    faceRotatedTooFarRight?: string;
    faceLookingTooFarLeft?: string;
    faceLookingTooFarRight?: string;
    faceNotInCamera?: string;
  };
  instructions?: {
    title?: string;
    subtitle?: string;
    titleLine2?: string;
    subtitleLine2?: string;
  };
  feedback?: {
    centerFace?: string;
    faceNotFound?: string;
    moveCloser?: string;
    moveBack?: string;
    moveEvenCloser?: string;
    moveLeft?: string;
    moveRight?: string;
    moveUp?: string;
    moveDown?: string;
    moveToEyeLevel?: string;
    lookStraightAhead?: string;
    faceNotUpright?: string;
    keepHeadStraight?: string;
    holdStill?: string;
    useEvenLighting?: string;
    tooBlurry?: string;
    multipleFacesDetected?: string;
    onlyOneFaceAllowed?: string;
    perfect?: string;
    readyToCapture?: string;
  };
  status?: {
    loading?: string;
    processing?: string;
    uploading?: string;
    analyzing?: string;
    initializing?: string;
    connectingCamera?: string;
    securingCamera?: string;
    success?: string;
    captureComplete?: string;
    verificationComplete?: string;
  };
  retry?: {
    title?: string;
    subtitle?: string;
    yourImageLabel?: string;
    idealImageLabel?: string;
    instructionBetterLighting?: string;
    instructionNeutralExpression?: string;
    instructionCleanCamera?: string;
    instructionBetterPosition?: string;
  };
  errors?: {
    cameraPermissionDenied?: string;
    cameraNotFound?: string;
    cameraInUse?: string;
    networkError?: string;
    uploadFailed?: string;
    sessionExpired?: string;
    sessionFailed?: string;
    faceNotDetected?: string;
    faceNotClear?: string;
    multipleFaces?: string;
    unexpectedError?: string;
    tryAgainLater?: string;
  };
  presession?: {
    frameYourFace?: string;
    lookStraightAhead?: string;
    eyesStraightAhead?: string;
    holdSteady?: string;
    neutralExpression?: string;
    removeDarkGlasses?: string;
    conditionsTooBright?: string;
    brightenEnvironment?: string;
  };
  cameraIssue?: {
    header?: string;
    headerMobile?: string;
    subheader?: string;
    subheaderMobile?: string;
    tableHeader1?: string;
    tableHeader2?: string;
    row1Issue?: string;
    row1Fix?: string;
    row1IssueFirefox?: string;
    row1FixFirefox?: string;
    row2Issue?: string;
    row2Fix?: string;
    row3Issue?: string;
    row3Fix?: string;
    subtableMessage?: string;
    action?: string;
    actionFirefox?: string;
  };
  cameraPermission?: {
    header?: string;
    message?: string;
  };
  fullscreen?: {
    header?: string;
    message?: string;
    action?: string;
  };
}

Exemplo — sobrescrever apenas o cabeçalho e o botão

const hubOptions = new window.LivenessFacetecSDK.HubOptions({
  locale: 'pt-BR',
  strings: {
    instructions: {
      title: 'Verificação Valid',
      subtitle: 'Centralize o seu rosto e clique em Estou Pronto',
    },
    actions: {
      ready: 'COMEÇAR',
      tryAgain: 'TENTAR DE NOVO',
    },
  },
});

Paleta de cores

A interface ColorTheme cobre superfícies, botões, detecção de rosto, resultado e branding. Sobrescreva apenas o subconjunto que faz sentido para a sua marca.

interface ColorTheme {
  // Superfícies
  backgroundColor?: string;  // Fundo principal
  surfaceColor?: string;      // Cards e painéis
  overlayColor?: string;      // Overlay / máscara de fundo

  // Texto
  textColor?: string;          // Texto primário
  textColorSecondary?: string; // Texto secundário / subtítulos

  // Botões
  buttonColor?: string;        // Background do botão
  buttonTextColor?: string;    // Texto do botão
  buttonHoverColor?: string;   // Estado hover
  buttonDisabledColor?: string; // Estado desabilitado

  // Detecção de rosto
  frameColor?: string;         // Oval / borda de detecção
  progressColor1?: string;     // Arco de progresso (cor 1)
  progressColor2?: string;     // Arco de progresso (cor 2)

  // Tela de resultado
  successColor?: string;           // Fundo do círculo na animação de sucesso
  successForegroundColor?: string; // Ícone / checkmark na animação de sucesso

  // Indicadores
  loadingColor?: string; // Spinner e indicadores de carregamento

  // Tela de proteção de câmera
  securingCameraTextColor?: string; // Texto da tela "Securing Camera Feed"

  // Branding
  brandingImage?: string; // Logo em URL ou data URI (base64)
}

Exemplo — tema com cores da Valid

const hubOptions = new window.LivenessFacetecSDK.HubOptions({
  colorTheme: {
    frameColor: '#B72819',
    progressColor1: '#B72819',
    progressColor2: '#8C1E12',
    successColor: '#16A34A',
    successForegroundColor: '#FFFFFF',
    buttonColor: '#B72819',
    buttonTextColor: '#FFFFFF',
    brandingImage: 'data:image/png;base64,iVBORw0KGgoAAAANSUh...',
  },
});

Temas prontos

O SDK exporta dois temas completos que podem ser usados como ponto de partida ou aplicados direto:

Tema	Quando usar
VALID_COLOR_THEME	Tema preto e branco, com a identidade da Valid
DEFAULT_COLOR_THEME	Tema neutro (default, aplicado quando colorTheme não é informado)

const { HubOptions, VALID_COLOR_THEME, VALID_LOGO_BASE64 } = window.LivenessFacetecSDK;

const hubOptions = new HubOptions({
  colorTheme: {
    ...VALID_COLOR_THEME,
    brandingImage: VALID_LOGO_BASE64,
  },
});

VALID_LOGO_BASE64 é a logo da Valid já em data:image/...;base64,... — útil para popular brandingImage sem hospedar a imagem.

Aplicando a customização

const { createFaceTecSDK, HubOptions } = window.LivenessFacetecSDK;

const sdk = createFaceTecSDK();

await sdk.run({
  mount: '#camera-container',
  env: 'production',
  onInit,
  hubOptions: new HubOptions({
    locale: 'pt-BR',
    strings: {
      instructions: { title: 'Verificação Valid' },
      errors: { cameraPermissionDenied: 'Permita o acesso à câmera nas configurações do navegador.' },
    },
    colorTheme: {
      frameColor: '#B72819',
      buttonColor: '#000000',
      buttonTextColor: '#FFFFFF',
    },
  }),
  onSuccess: (result) => console.log(result),
  onFailure: (error) => console.error(error),
});

Próximos passos

Implementação

Volte para a referência de uso do SDK

Solução de problemas

Hierarquia de erros e diagnóstico