Skip to main content
Este guia mostra a API pública do LivenessFacetecSDK e o fluxo completo de uma verificação no browser. O bundle expõe window.LivenessFacetecSDK com uma fábrica que cria a instância do SDK. A única interface que você precisa conhecer é a FaceTecSDKConfig — o objeto de configuração que você passa para executar uma verificação. 
const sdk = window.LivenessFacetecSDK.createFaceTecSDK();
const result = await sdk.run(config); // config: FaceTecSDKConfig
sdk.run(config) orquestra o fluxo completo (preparação, captura, submissão e limpeza) em uma única chamada e resolve com o LivenessResult da verificação.

​
Configuração

interface FaceTecSDKConfig {
  mount: HTMLElement | string;
  onInit: (params: SessionParams) => Promise<SessionTokens>;
  hubOptions?: HubOptions;
  onSuccess?: (result: LivenessResult) => void;
  onFailure?: (error: LivenessFailureError) => void;
  onProgress?: (state: HubState) => void;
}
ParâmetroTipoObrigatórioDescrição
mount`HTMLElementstring`SimElemento (ou seletor CSS) onde a UI da câmera vai renderizar.
onInit(params) => Promise<SessionTokens>SimCallback que seu código implementa: chama o seu backend, que implementa o serviço de Facetec, e devolve sessionToken, facetecSessionToken e sessionId.
hubOptionsHubOptionsNãoPersonalização de idioma, textos e cores. Veja Customização.
onSuccess(result) => voidNãoDisparado quando a captura termina (mesmo quando livenessCheck = false — é um resultado biométrico, não um erro técnico).
onFailure(error) => voidNãoDisparado quando o fluxo técnico falha. Veja Solução de problemas.
onProgress(state) => voidNãoRecebe transições de estado (Uninitialized, Initializing, Ready, Capturing, Closing, Error).

​
Como o onInit funciona

O SDK chama onInit antes de inicializar a UI, passando metadados de dispositivo coletados pelo FingerprintJS Pro: 
interface SessionParams {
  visitorId?: string;
  eventId?: string;
}
Você repassa esses metadados ao seu backend e devolve ao SDK os três tokens da sessão: 
interface SessionTokens {
  sessionId: string;
  sessionToken: string;
  facetecSessionToken: string;
}
Nem sempre o SDK consegue obter o visitorId e o eventId — depende de conectividade, configurações de privacidade e do ambiente de execução. Repasse-os ao seu backend quando estiverem presentes; quando ausentes, o serviço cria a sessão normalmente. Veja Serviço.
maxAttempts — seu backend pode incluir este campo ao chamar POST /api/v1/sessions, definindo o número máximo de capturas biométricas permitidas na sessão (1–5, default 3). Quando uma captura falha e ainda há tentativas disponíveis, o FaceTec exibe a tela de retry automaticamente sem criar nova sessão.

​
Fluxo de uso

1

Crie a instância do SDK

Logo após o bundle ser carregado, crie a instância. Você pode reaproveitá-la em múltiplas capturas.
const sdk = window.LivenessFacetecSDK.createFaceTecSDK();
2

Implemente o onInit chamando o seu backend

O onInit é um async que devolve { sessionId, sessionToken, facetecSessionToken }. Encaminhe os sessionParams recebidos para o seu endpoint:
async function onInit(sessionParams) {
  const r = await fetch('api.client.com/api/create-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(sessionParams), // { visitorId?, eventId? }
  });

  if (!r.ok) {
    const err = await r.json().catch(() => ({}));
    throw new Error(`Falha ao criar sessão: ${r.status} ${err.error?.message ?? ''}`);
  }

  return r.json(); // { sessionId, sessionToken, facetecSessionToken }
}
3

Dispare a verificação

document.getElementById('iniciar-verificacao').addEventListener('click', async () => {
  try {
    const result = await sdk.run({
      mount: '#camera-container',
      onInit,
      onSuccess: (data) => console.log('verificado', data),
      onFailure: (error) => console.error('falhou', error.type, error.failureReason),
      onProgress: (state) => console.log('estado', state),
    });

    // result === o mesmo objeto entregue ao onSuccess
    console.log('sessionId', result.sessionId);
  } catch (err) {
    // Erros inesperados não cobertos por onFailure
    console.error('erro inesperado', err);
  }
});
4

Trate o resultado

Use sessionId e captureId para reconciliar a captura no seu backend. Se verified === false, exiba mensagem ao usuário e ofereça nova tentativa — não é um erro técnico, é uma reprovação biométrica.

​
Campos de LivenessResult

Quando a captura termina, o SDK emite o objeto abaixo via onSuccess (e também resolve a Promise de run com ele): 
interface LivenessResult {
  sessionId: string;
  captureId: string;
  verified: boolean;
  status: 'completed' | 'failed';
  processingTime: number;
  base64Data?: string;
  failureReason?: string;
  processedAt?: string;
  retryScreen?: number;
  auditTrailCheck?: boolean;
  replayCheck?: boolean;
  sessionTokenCheck?: boolean;
  livenessCheck?: boolean;
  attemptsLeft?: number;
}
CampoTipoDescrição
sessionIdstringID da sessão criada na Plataforma ID.
captureIdstringID único da captura submetida.
verifiedbooleanResultado consolidado — true quando o liveness foi aprovado.
status`‘completed''failed’`Estado da captura no backend.
processingTimenumberTempo total de processamento em milissegundos.
livenessCheckboolean?Resultado isolado da verificação de vivacidade.
auditTrailCheckboolean?Validação da trilha de auditoria.
replayCheckboolean?Resultado da verificação anti-replay.
sessionTokenCheckboolean?Validação do token de sessão.
failureReasonstring?Motivo da falha, quando aplicável.
processedAtstring?Timestamp ISO-8601 do processamento.
retryScreennumber?Indicador interno de retry do FaceTec.
base64Datastring?Dado biométrico opcional.
attemptsLeftnumber?Tentativas restantes no momento da aprovação.
Os quatro *Check são as garantias de segurança consolidadas pelo backend. Em uma captura legítima, todos devem ser true.

​
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>FaceTec Demo</title>
    <script src="https://cdn.hub-liveness-service.app/facetec/latest/prd/facetec-sdk.js"></script>
  </head>
  <body>
    <button id="iniciar">Iniciar Verificação</button>
    <div id="camera-container" style="width: 480px; height: 480px; background: #000;"></div>
    <pre id="resultado"></pre>

    <script>
      const sdk = window.LivenessFacetecSDK.createFaceTecSDK();
      const resultadoEl = document.getElementById('resultado');

      async function onInit(sessionParams) {
        const r = await fetch('/api/create-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(sessionParams),
        });
        if (!r.ok) throw new Error(`Sessão falhou: ${r.status}`);
        return r.json();
      }

      document.getElementById('iniciar').addEventListener('click', async () => {
        resultadoEl.textContent = 'Processando…';
        try {
          await sdk.run({
            mount: '#camera-container',
            env: 'production',
            onInit,
            onSuccess: (data) => {
              resultadoEl.textContent = JSON.stringify(data, null, 2);
            },
            onFailure: (error) => {
              resultadoEl.textContent = `Falhou: ${error.type} — ${error.failureReason ?? ''}`;
            },
          });
        } catch (err) {
          resultadoEl.textContent = `Erro: ${err.message}`;
        }
      });
    </script>
  </body>
</html>

​
Próximos passos

Customização

Locales, textos e paleta de cores da UI

Solução de problemas

Hierarquia de erros e diagnóstico