Troubleshooting

Tipos de Erro

O SDK categoriza erros em tipos específicos para facilitar o tratamento:

enum LivenessErrorType {
  INITIALIZATION_FAILED = 'INITIALIZATION_FAILED',       // Falha na inicialização
  SESSION_FAILED = 'SESSION_FAILED',                     // Falha ao criar sessão ou sessão expirada
  CAPTURE_FAILED = 'CAPTURE_FAILED',                     // Falha na captura
  LIVENESS_VALIDATION_FAILED = 'LIVENESS_VALIDATION_FAILED', // Reprovado na validação de vivacidade
  SUBMISSION_FAILED = 'SUBMISSION_FAILED',               // Falha no envio ao backend
  CAMERA_PERMISSION_DENIED = 'CAMERA_PERMISSION_DENIED', // Permissão de câmera negada
  CAMERA_INJECTION_DETECTED = 'CAMERA_INJECTION_DETECTED', // Injeção de câmera virtual detectada
  USER_CANCELLED = 'USER_CANCELLED',                     // Usuário cancelou
  NETWORK_ERROR = 'NETWORK_ERROR',                       // Erro de rede
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',                       // Erro desconhecido
}

Estrutura do Erro

interface LivenessFailureError {
  type: LivenessErrorType; // Tipo do erro
  failureReason?: string;  // Descrição detalhada (opcional)
}

Tratamento de Erros

Usando Callback

const config = {
  // ... outras configurações

  onFailure: (error) => {
    switch (error.type) {
      case 'CAMERA_PERMISSION_DENIED':
        mostrarMensagem(
          'Por favor, permita o acesso à câmera nas configurações do navegador.'
        );
        break;

      case 'CAMERA_INJECTION_DETECTED':
        mostrarMensagem(
          'Detectamos um problema com a câmera. Por favor, desative softwares de câmera virtual.'
        );
        break;

      case 'NETWORK_ERROR':
        mostrarMensagem(
          'Erro de conexão. Verifique sua internet e tente novamente.'
        );
        break;

      case 'SESSION_FAILED':
        mostrarMensagem(
          'Não foi possível iniciar a sessão. Tente novamente em alguns instantes.'
        );
        break;

      case 'LIVENESS_VALIDATION_FAILED':
        mostrarMensagem(
          'A verificação de vivacidade não foi aprovada. Tente novamente seguindo as instruções.'
        );
        break;

      case 'CAPTURE_FAILED':
        mostrarMensagem(
          'Falha na captura: ' + (error.failureReason || 'Tente novamente')
        );
        break;

      case 'USER_CANCELLED':
        mostrarMensagem('Verificação cancelada pelo usuário.');
        break;

      default:
        mostrarMensagem('Ocorreu um erro inesperado. Tente novamente.');
        console.error('Erro:', error);
    }
  },
};

Usando try/catch

try {
  const result = await hub.run(config);
  processarResultado(result);
} catch (error) {
  if (error.type) {
    // Erro tipado do SDK
    tratarErroLiveness(error);
  } else {
    // Erro genérico
    console.error('Erro inesperado:', error);
  }
}

Mensagens Amigáveis

Converta erros técnicos em mensagens compreensíveis para o usuário:

function getMensagemAmigavel(error) {
  const mensagens = {
    CAMERA_PERMISSION_DENIED: {
      titulo: 'Acesso à Câmera Necessário',
      mensagem:
        'Para continuar, permita o acesso à câmera nas configurações do seu navegador.',
      acao: 'Verificar Permissões',
    },
    CAMERA_INJECTION_DETECTED: {
      titulo: 'Câmera Virtual Detectada',
      mensagem:
        'Detectamos um software de câmera virtual. Por favor, desative-o e use sua câmera real.',
      acao: 'Tentar Novamente',
    },
    NETWORK_ERROR: {
      titulo: 'Problema de Conexão',
      mensagem:
        'Não foi possível conectar ao servidor. Verifique sua internet.',
      acao: 'Tentar Novamente',
    },
    SESSION_FAILED: {
      titulo: 'Falha na Sessão',
      mensagem: 'A sessão expirou ou não pôde ser criada. Por favor, inicie novamente.',
      acao: 'Reiniciar',
    },
    LIVENESS_VALIDATION_FAILED: {
      titulo: 'Verificação Não Aprovada',
      mensagem:
        'A verificação de vivacidade não foi aprovada. Siga as instruções na tela e tente novamente.',
      acao: 'Tentar Novamente',
    },
    CAPTURE_FAILED: {
      titulo: 'Falha na Captura',
      mensagem:
        'Não conseguimos capturar sua biometria. Tente novamente com boa iluminação.',
      acao: 'Tentar Novamente',
    },
    SUBMISSION_FAILED: {
      titulo: 'Falha no Envio',
      mensagem:
        'Não foi possível enviar os dados. Verifique sua conexão e tente novamente.',
      acao: 'Tentar Novamente',
    },
    USER_CANCELLED: {
      titulo: 'Verificação Cancelada',
      mensagem: 'Você cancelou a verificação.',
      acao: 'Reiniciar',
    },
  };

  return (
    mensagens[error.type] || {
      titulo: 'Erro Inesperado',
      mensagem: 'Ocorreu um problema. Por favor, tente novamente.',
      acao: 'Tentar Novamente',
    }
  );
}

Content Security Policy (CSP)

Se a sua aplicação utiliza Content Security Policy, você precisará permitir as seguintes origens para que o SDK funcione corretamente:

script-src 'self' https://storage.googleapis.com/hub-sdk-cdn/;
connect-src 'self' https://hub-liveness-service.app https://*.facetec.com;
img-src 'self' blob: data:;
media-src 'self' blob:;
worker-src 'self' blob:;

Diretiva	Origem	Motivo
`script-src`	`https://storage.googleapis.com/hub-sdk-cdn/`	CDN do SDK
`connect-src`	`https://hub-liveness-service.app` `https://hml-api.hub-liveness-service.app`	Comunicação com a API de liveness (URLs gerenciadas pelo SDK)
`connect-src`	`https://*.facetec.com`	Recursos do motor FaceTec (quando utilizado)
`img-src`	`blob:` `data:`	Imagens capturadas pela câmera e assets em base64
`media-src`	`blob:`	Stream de vídeo da câmera
`worker-src`	`blob:`	Web Workers usados internamente pelo SDK

As origens exatas podem variar dependendo do motor biométrico selecionado (FaceSDK, FaceTec ou Innovatrics). Em caso de erros de CSP no console, adicione as origens bloqueadas à sua política.

Boas Práticas

Segurança

API Key

Nunca exponha a API Key no código frontend em produção. Use variáveis de ambiente ou carregue de um endpoint seguro.

Arquivo CEK

Mantenha o CEK em um endpoint com autenticação. Considere carregá-lo dinamicamente quando necessário.

HTTPS

O SDK requer conexão segura em produção. A API getUserMedia só funciona em contextos seguros (HTTPS ou localhost).

Validação

Valide os resultados no seu backend antes de confiar neles.

Performance

Pré-carregue o CEK

Carregue o CEK antes do usuário iniciar a verificação para evitar delays.

Container com dimensões fixas

Defina dimensões fixas no container para evitar reflows durante a renderização.

Cleanup na API Avançada

Se estiver usando a API Avançada (init / startLivenessCheck / teardown), sempre chame teardown() em um bloco finally. Na API Simples (run()), o cleanup é automático.

// Cleanup automático, sem necessidade de teardown
const hub = ValidHub.createHub();

try {
  const result = await hub.run(config);
  // processar resultado
} catch (error) {
  // tratar erro
}

// Teardown obrigatório
const hub = ValidHub.createHub();

try {
  await hub.init(config);
  const result = await hub.startLivenessCheck();
  // processar resultado
} finally {
  await hub.teardown();
}

Experiência do Usuário

Feedback Visual

Use os callbacks onProgress para mostrar feedback ao usuário durante cada etapa.

Mensagens Claras

Traduza os erros técnicos em mensagens compreensíveis para o usuário final.

Instruções Claras

Personalize as instruções para seu público-alvo usando hubOptions.strings.

Ambiente Adequado

Oriente o usuário sobre iluminação e posicionamento antes de iniciar a verificação.

Integração com Frameworks

Serviço Reutilizável

// livenessService.js
class LivenessService {
  constructor(config) {
    this.config = config;
    this.hub = null;
  }

  async carregarCEK(cekUrl) {
    const response = await fetch(cekUrl);
    if (!response.ok) {
      throw new Error('Falha ao carregar CEK');
    }
    return await response.json();
  }

  async verificar(options = {}) {
    if (typeof ValidHub === 'undefined') {
      throw new Error('SDK não carregado');
    }

    const cekData = await this.carregarCEK(this.config.cekUrl);
    this.hub = ValidHub.createHub();

    const hubConfig = {
      apiKey: this.config.apiKey,
      cek: cekData,
      mount: options.container || this.config.defaultContainer,
      env: this.config.env,
      appName: this.config.appName,
      risk: options.risk || 'LIVENESS_RISK_HIGH',
      hubOptions: options.hubOptions,
      onProgress: options.onProgress,
      onSuccess: options.onSuccess,
      onFailure: options.onFailure,
    };

    try {
      const result = await this.hub.run(hubConfig);
      return result;
    } finally {
      this.hub = null;
    }
  }

  async cancelar() {
    if (this.hub) {
      await this.hub.teardown();
      this.hub = null;
    }
  }
}

// Uso
const livenessService = new LivenessService({
  apiKey: 'sua-api-key',
  cekUrl: '/config/production.cek.json',
  env: 'production',
  appName: 'minha-aplicacao',
  defaultContainer: '#camera-container',
});

async function handleVerificacao() {
  try {
    const result = await livenessService.verificar({
      risk: 'LIVENESS_RISK_HIGH',
      hubOptions: {
        locale: 'pt-BR',
        colorTheme: { primaryColor: '#0066cc' },
      },
      onProgress: (state) => atualizarUI(state),
    });

    await enviarResultadoParaBackend(result);
  } catch (error) {
    tratarErro(error);
  }
}

Checklist de Verificação

Antes de reportar um problema, verifique os itens abaixo:

SDK Carregado

Confirme que o script do SDK foi carregado corretamente (ValidHub está disponível globalmente).

HTTPS

A página está sendo servida via HTTPS (obrigatório para acesso à câmera). Em desenvolvimento, localhost é aceito.

Navegador Compatível

Verifique se o navegador suporta WebCrypto API e getUserMedia (Chrome 60+, Firefox 55+, Safari 14.1+, Edge 79+).

CEK Válido

O CEK está acessível e não expirou.

Credenciais

API Key está correta e o ambiente (env) está configurado corretamente.

Container

O elemento container existe no DOM antes de chamar hub.run().

Permissões

O navegador tem permissão para acessar a câmera.

CSP

Se a sua aplicação usa Content Security Policy, verifique se as origens necessárias estão permitidas (veja seção CSP acima).

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

BPO

Extração Dados

Mensageria

Documentoscopia

Tipos de Erro

Estrutura do Erro

Tratamento de Erros

Usando Callback

Usando try/catch

Mensagens Amigáveis

Content Security Policy (CSP)

Boas Práticas

Segurança

API Key

Arquivo CEK

HTTPS

Validação

Performance

Experiência do Usuário

Feedback Visual

Mensagens Claras

Instruções Claras

Ambiente Adequado

Integração com Frameworks

Serviço Reutilizável

Checklist de Verificação

Referências

Instalação

Implementação

​Tipos de Erro

​Estrutura do Erro

​Tratamento de Erros

​Usando Callback

​Usando try/catch

​Mensagens Amigáveis

​Content Security Policy (CSP)

​Boas Práticas

​Segurança

API Key

Arquivo CEK

HTTPS

Validação

​Performance

​Experiência do Usuário

Feedback Visual

Mensagens Claras

Instruções Claras

Ambiente Adequado

​Integração com Frameworks

​Serviço Reutilizável

​Checklist de Verificação

​Referências

Instalação

Implementação

Tipos de Erro

Estrutura do Erro

Tratamento de Erros

Usando Callback

Usando try/catch

Mensagens Amigáveis

Content Security Policy (CSP)

Boas Práticas

Segurança

Performance

Experiência do Usuário

Integração com Frameworks

Serviço Reutilizável

Checklist de Verificação

Referências