Implementação

Este guia mostra a API pública do LivenessFacetecSDK v10 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 (inicialização, captura, submissão e limpeza) em uma única chamada e resolve com o LivenessResult da verificação. Não há um elemento de montagem — a captura abre como camada full-screen sobre a página.

Configuração

interface FaceTecSDKConfig {
  onInit: (params: SessionParams) => Promise<SessionTokens>;
  backendBaseUrl?: string;
  env?: 'production' | 'development' | 'homolog';
  options?: FaceTecOptionsInput;
  onSuccess?: (result: LivenessResult) => void;
  onFailure?: (error: LivenessFailureError) => void;
  onProgress?: (state: HubState) => void;
}

Parâmetro	Tipo	Obrigatório	Descrição
`onInit`	`(params) => Promise<SessionTokens>`	Sim	Callback que seu código implementa: chama o seu backend, que chama o serviço FaceTec, e devolve `sessionId` e `sessionToken`.
`backendBaseUrl`	`string`	Não	Substitui a URL de backend embutida no bundle. Use apenas em desenvolvimento local, apontando para um proxy próprio.
`env`	`'production' \| 'development' \| 'homolog'`	Não	Controla apenas o envio de diagnósticos (Sentry) — não seleciona qual backend o SDK usa. O backend já é fixo no bundle carregado (veja Instalação).
`options`	`FaceTecOptionsInput`	Não	Idioma, textos e customização visual. Veja Customização.
`onSuccess`	`(result) => void`	Não	Disparado quando a captura termina (mesmo quando `verified = false` — é um resultado biométrico, não um erro técnico).
`onFailure`	`(error) => void`	Não	Disparado quando o fluxo técnico falha. Veja Solução de problemas.
`onProgress`	`(state) => void`	Não	Recebe transições de estado (`Uninitialized`, `Initializing`, `Ready`, `Capturing`, `Processing`, `Closing`).

Como o `onInit` funciona

O SDK chama onInit antes de abrir a captura, passando metadados de dispositivo coletados pelo Shield Web SDK:

interface SessionParams {
  ssid?: string;
}

Você repassa esse metadado ao seu backend e devolve ao SDK os dois tokens da sessão:

interface SessionTokens {
  sessionId: string;
  sessionToken: string;
}

Nem sempre o SDK consegue obter o ssid — depende de conectividade e do ambiente de execução. Repasse-o ao seu backend quando estiver presente; quando ausente, o serviço cria a sessão normalmente. Veja Serviço.

Não existe mais maxAttempts nem uma segunda tela de retry dentro da mesma sessão. Para tentar de novo após uma falha, chame sdk.run() outra vez — isso reaproveita a instância já inicializada e cria uma sessão nova automaticamente.

Fluxo de uso

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 — inclusive em retries.

const sdk = window.LivenessFacetecSDK.createFaceTecSDK();

Implemente o onInit chamando o seu backend

O onInit é um async que devolve { sessionId, sessionToken }. Encaminhe os sessionParams recebidos para o seu endpoint:

async function onInit(sessionParams) {
  const r = await fetch('/api/create-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(sessionParams), // { ssid? }
  });

  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 }
}

Dispare a verificação

document.getElementById('iniciar-verificacao').addEventListener('click', async () => {
  try {
    const result = await sdk.run({
      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);
  }
});

Trate o resultado

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

Campos de `LivenessResult`

Quando a captura termina com sucesso, o SDK emite o objeto abaixo via onSuccess (e também resolve a Promise de run com ele):

interface LivenessResult {
  sessionId: string;
  verified: boolean;
  processingTime: number;
  base64Image?: string;
  ageGroup?: number;
}

Campo	Tipo	Descrição
`sessionId`	`string`	ID da sessão criada pelo serviço.
`verified`	`boolean`	Resultado consolidado — `true` quando o liveness foi aprovado.
`processingTime`	`number`	Tempo total de processamento em milissegundos.
`base64Image`	`string?`	Imagem da captura, quando disponível.
`ageGroup`	`number?`	Estimativa de faixa etária, quando o FaceTec retorna esse dado.

Outros métodos do SDK

interface FaceTecSDKInterface {
  run(config: FaceTecSDKConfig): Promise<LivenessResult>;
  unload(): Promise<void>;
  isLockedOut(): boolean | undefined;
  getLockoutEndTime(): number | null | undefined;
}

Método	Descrição
`isLockedOut()`	`true`/`false` indicam o estado de bloqueio do dispositivo. `undefined` significa que o motor FaceTec ainda não carregou — não interprete como “não bloqueado”.
`getLockoutEndTime()`	Timestamp (ms) de quando o bloqueio termina. `null` = não bloqueado, `undefined` = motor ainda não carregado.
`unload()`	Libera a instância do motor FaceTec e limpa o cache interno. Não é obrigatório chamar (um reload de página também libera tudo) — útil em SPAs ao desmontar a rota que usa o SDK. Uma nova chamada a `run()` reinicializa tudo normalmente.

Preload

window.LivenessFacetecSDK.preload(): Promise<void>

preload() é uma função independente (não é um método da instância criada por createFaceTecSDK()) que busca antecipadamente tudo o que run() vai precisar: o script vendor do FaceTec e a inicialização do Shield, em paralelo. Nenhum dos dois depende de sessão — por isso pode rodar bem antes de qualquer captura começar.

Você normalmente não precisa chamar isso. O próprio bundle já executa preload() automaticamente assim que o <script> termina de carregar.

Chame manualmente apenas se você carrega o <script> do SDK de forma tardia (ex.: injetado dinamicamente só quando o usuário chega perto da etapa de verificação) e quer adiantar o carregamento do motor FaceTec para antes disso — por exemplo, assim que o usuário entra em uma tela anterior do seu fluxo:

// Em uma etapa anterior à verificação, assim que o SDK estiver disponível:
window.LivenessFacetecSDK.preload();

É seguro chamar mais de uma vez (as buscas internas são cacheadas/idempotentes) e seguro ignorar a Promise retornada.

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/v10/latest/prd/facetec-sdk.js"></script>
  </head>
  <body>
    <button id="iniciar">Iniciar Verificação</button>
    <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({
            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>

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Configuração

Como o `onInit` funciona

Fluxo de uso

Campos de `LivenessResult`

Outros métodos do SDK

Preload

Exemplo completo

Próximos passos

Customização

Solução de problemas

​Configuração

​Como o onInit funciona

​Fluxo de uso

​Campos de LivenessResult

​Outros métodos do SDK

​Preload

​Exemplo completo

​Próximos passos

Customização

Solução de problemas

Configuração

Como o `onInit` funciona

Fluxo de uso

Campos de `LivenessResult`

Outros métodos do SDK

Preload

Exemplo completo

Próximos passos