Skip to main content

​
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: 
// Criar instância do Hub
const hub = ValidHub.createHub();

// Configuração do SDK
const config = {
  apiKey: 'sua-api-key',
  cek: cekData, // Dados do CEK (ver seção de instalação)
  mount: '#camera-container',
  backendBaseUrl: 'https://api.valid.com/liveness',
  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);
}

​
API Avançada (Controle Granular)

Para cenários que requerem maior controle sobre o fluxo: 
const hub = ValidHub.createHub();

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

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

// Passo 3: Limpar recursos (obrigatório)
await hub.teardown();

​
Estrutura de Configuração

interface HubConfig {
  // Obrigatórios
  apiKey: string; // Chave de API
  cek: string | CEKData; // Dados do CEK
  mount: HTMLElement | string; // Elemento ou seletor CSS do container

  // Opcionais
  backendBaseUrl?: string; // URL do backend
  appName?: string; // Nome da aplicação
  risk?: string; // Nível de risco
  debug?: boolean; // Modo debug
  hubOptions?: HubOptions; // Opções de personalização

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

​
Níveis de Risco

ValorDescrição
LIVENESS_RISK_HIGHVerificação mais rigorosa
LIVENESS_RISK_MEDIUMVerificação moderada
LIVENESS_RISK_LOWVerificação básica

​
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 funciona 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://cdn.valid.com/liveness-sdk/latest/valid-hub-sdk.min.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');
      let cekData = null;

      // Carregar CEK ao iniciar
      fetch('/config/meu-cek.json')
        .then((res) => res.json())
        .then((data) => {
          cekData = data;
        })
        .catch((err) => console.error('Erro ao carregar CEK:', err));

      btnVerificar.addEventListener('click', async () => {
        if (!cekData) {
          mostrarMensagem('CEK não carregado', 'error');
          return;
        }

        btnVerificar.disabled = true;
        mensagemDiv.innerHTML = '';

        const hub = ValidHub.createHub();

        try {
          const result = await hub.run({
            apiKey: 'sua-api-key',
            cek: cekData,
            mount: '#camera-container',
            backendBaseUrl: 'https://api.valid.com/liveness',
            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