Implementação

Como implementar a verificação de liveness na sua aplicação web

APIs Disponíveis

O SDK oferece duas formas de utilização: API Simples (recomendada) e API Avançada.

API Simples (Recomendada)

Use o método run() para executar todo o fluxo de verificação com uma única chamada. O método gerencia automaticamente a inicialização, captura e limpeza de recursos.

// Criar instância do Hub
const hub = ValidHub.createHub();

// Configuração do SDK
const config = {
  apiKey: 'sua-api-key',
  cek: 'sua-cek-base64',
  mount: '#camera-container',
  env: 'production',
  appName: 'minha-aplicacao',
  risk: 'LIVENESS_RISK_HIGH',

  // Callbacks
  onSuccess: (result) => {
    console.log('Verificação bem sucedida:', result);
  },
  onFailure: (error) => {
    console.error('Verificação falhou:', error);
  },
  onProgress: (state) => {
    console.log('Progresso:', state);
  },
};

// Executar verificação
try {
  const result = await hub.run(config);
  console.log('Resultado:', result);
} catch (error) {
  console.error('Erro:', error);
}

O método run() gerencia o ciclo de vida completo, incluindo o teardown automático ao final. Você não precisa chamar teardown() ao usar a API Simples.

API Avançada (Controle Granular)

Para cenários que requerem maior controle sobre o fluxo:

const hub = ValidHub.createHub();

try {
  // Passo 1: Inicializar o SDK
  await hub.init(config);

  // Passo 2: Executar a verificação quando necessário
  const result = await hub.startLivenessCheck();

  // Processar resultado
  console.log('Resultado:', result);
} finally {
  // Passo 3: Limpar recursos (obrigatório na API Avançada)
  await hub.teardown();
}

Na API Avançada, é obrigatório chamar teardown() para liberar recursos (câmera, memória, listeners). Use um bloco finally para garantir a limpeza mesmo em caso de erro.

Estrutura de Configuração

interface HubConfig {
  // Obrigatórios
  apiKey: string;                              // Chave de API
  cek: string | ArrayBufferView | CEKData;     // CEK (ver formatos aceitos na página de Instalação)
  mount: HTMLElement | string;                 // Elemento ou seletor CSS do container

  // Opcionais
  appName?: string;                            // Nome da aplicação
  risk?: string;                               // Nível de risco (ver tabela abaixo)
  debug?: boolean;                             // Modo debug (logs detalhados no console)
  env?: 'production' | 'development' | 'homolog'; // Ambiente de execução e URL do backend
  hubOptions?: HubOptions;                     // Opções de personalização (idioma, tema, UI)

  // Callbacks
  onSuccess?: (result: LivenessResult) => void;
  onFailure?: (error: LivenessFailureError) => void;
  onProgress?: (state: HubState) => void;
}

Parâmetros Detalhados

Parâmetro	Tipo	Descrição
cek	string | ArrayBufferView | CEKData	Aceita string Base64, JSON string, ou objeto CEKData diretamente. Veja os formatos aceitos.
env	'production' | 'development' | 'homolog'	Define o ambiente de execução e a URL do backend automaticamente. Padrão: 'production'.

Níveis de Risco

O nível de risco determina qual motor biométrico o backend seleciona automaticamente:

Valor	Motor Padrão	Descrição
LIVENESS_RISK_HIGH	FaceTec	Verificação mais rigorosa com liveness 3D ativo
LIVENESS_RISK_MEDIUM	FaceSDK	Verificação moderada com detecção de vivacidade
LIVENESS_RISK_LOW	FaceSDK	Verificação básica

A seleção do motor biométrico é feita automaticamente pelo backend com base no nível de risco. Não é possível sobrescrever essa seleção no client-side.

Sessões

Cada chamada ao SDK cria uma sessão no backend com os seguintes parâmetros padrão:

Parâmetro	Valor Padrão	Faixa Permitida	Descrição
TTL	300 segundos (5 min)	60 – 600 s	Tempo máximo de vida da sessão

Cada sessão permite uma única tentativa de captura. Se a sessão expirar ou a captura falhar, o SDK retornará um erro do tipo SESSION_FAILED e uma nova chamada deve ser realizada para criar uma sessão nova.

Estados do SDK

O SDK passa por diferentes estados durante o processo de verificação:

enum HubState {
  Uninitialized = 'uninitialized', // SDK não inicializado
  Initializing = 'initializing',   // Em processo de inicialização
  Ready = 'ready',                 // Pronto para verificação
  Capturing = 'capturing',         // Capturando biometria
  Closing = 'closing',             // Encerrando sessão
  Error = 'error',                 // Estado de erro
}

Monitorando Estados

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

  onProgress: (state) => {
    switch (state) {
      case 'uninitialized':
        console.log('SDK ainda não foi inicializado');
        break;
      case 'initializing':
        mostrarLoader('Preparando sistema...');
        break;
      case 'ready':
        esconderLoader();
        console.log('Pronto para iniciar verificação');
        break;
      case 'capturing':
        console.log('Captura em andamento...');
        break;
      case 'closing':
        mostrarLoader('Finalizando...');
        break;
      case 'error':
        esconderLoader();
        console.error('Ocorreu um erro');
        break;
    }
  },
};

Modelo de Resposta

Resposta de Sucesso (LivenessResult)

Quando a verificação é concluída com sucesso:

interface LivenessResult {
  sessionId: string;      // ID único da sessão
  captureId: string;      // ID único da captura
  verified: boolean;      // Indica se a verificação foi bem sucedida
  status: 'completed' | 'failed' | 'expired'; // Status da verificação
  processingTime: number; // Tempo de processamento em milissegundos
  base64Data?: string;    // Imagem capturada em Base64 (não disponível para todos os motores)
  failureReason?: string; // Motivo da falha (quando aplicável)
}

Exemplo de Resposta

{
  "sessionId": "sess_abc123xyz",
  "captureId": "cap_def456uvw",
  "verified": true,
  "status": "completed",
  "processingTime": 2340,
  "base64Data": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}

Utilizando a Resposta

hub
  .run(config)
  .then((result) => {
    if (result.verified && result.status === 'completed') {
      // Verificação bem sucedida
      console.log('Sessão:', result.sessionId);
      console.log('Captura:', result.captureId);
      console.log('Tempo de processamento:', result.processingTime, 'ms');

      // Usar a imagem capturada (se disponível)
      if (result.base64Data) {
        const img = document.createElement('img');
        img.src = result.base64Data;
        document.body.appendChild(img);
      }

      // Enviar resultado para seu backend
      enviarParaBackend(result);
    }
  })
  .catch((error) => {
    console.error('Falha na verificação:', error);
  });

Exemplo Completo

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Verificação Liveness</title>
    <script src="https://storage.googleapis.com/hub-sdk-cdn/v1.4.3/prod/valid-hub-sdk.js"></script>
    <style>
      .container {
        max-width: 500px;
        margin: 50px auto;
        padding: 20px;
        text-align: center;
      }
      #camera-container {
        width: 100%;
        max-width: 400px;
        aspect-ratio: 9/19.5;
        margin: 20px auto;
        border-radius: 24px;
        background: #f0f0f0;
      }
      .btn {
        padding: 15px 30px;
        font-size: 16px;
        background: #667eea;
        color: white;
        border: none;
        border-radius: 8px;
        cursor: pointer;
      }
      .btn:disabled {
        background: #ccc;
        cursor: not-allowed;
      }
      .message {
        margin-top: 20px;
        padding: 15px;
        border-radius: 8px;
      }
      .success {
        background: #d4edda;
        color: #155724;
      }
      .error {
        background: #f8d7da;
        color: #721c24;
      }
    </style>
  </head>
  <body>
    <div class="container">
      <h1>Verificação de Identidade</h1>
      <div id="camera-container"></div>
      <button id="btn-verificar" class="btn">Iniciar Verificação</button>
      <div id="mensagem"></div>
    </div>

    <script>
      const btnVerificar = document.getElementById('btn-verificar');
      const mensagemDiv = document.getElementById('mensagem');

      // CEK fornecido como string Base64
      const cek = 'sua-cek-base64';

      btnVerificar.addEventListener('click', async () => {
        btnVerificar.disabled = true;
        mensagemDiv.innerHTML = '';

        const hub = ValidHub.createHub();

        try {
          const result = await hub.run({
            apiKey: 'sua-api-key',
            cek: cek,
            mount: '#camera-container',
            env: 'production',
            risk: 'LIVENESS_RISK_HIGH',
          });

          mostrarMensagem(
            `Verificação concluída! ID: ${result.captureId}`,
            'success',
          );
        } catch (error) {
          mostrarMensagem(`Erro: ${error.type || error.message}`, 'error');
        } finally {
          btnVerificar.disabled = false;
        }
      });

      function mostrarMensagem(texto, tipo) {
        mensagemDiv.innerHTML = `<div class="message ${tipo}">${texto}</div>`;
      }
    </script>
  </body>
</html>

Próximos Passos

Customização

Personalize idiomas, textos e cores

Troubleshooting

Tratamento de erros e boas práticas