Vanilla JS

Monte o widget de verificação com uma tag script e nada mais: sem npm, sem bundler, sem build.

Ao final deste guia o fluxo de verificação abre numa página HTML estática, sem passo de build.

Comece por aqui se é a sua primeira integração. Se o widget funciona aqui, funciona em qualquer lugar onde um navegador rode, os outros guias existem para provar que um framework não atrapalha, não para provar que o SDK funciona.

Pré-requisitos

• Um navegador moderno.
• Uma sdkUrl emitida pelo seu backend, como em emitir a credencial. O SDK nunca gera uma sozinho.
• Um servidor HTTP local. Alguns navegadores bloqueiam a câmera em origem file://.

Confira o exemplo

A árvore de arquivos desta integração, com o destino de cada um.

Monte o fluxo

1. Crie a página

   O widget renderiza dentro de um elemento seu e ocupa 100% da altura dele. Sem altura, ele existe na página e não aparece.

   index.html

   <!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</title>
     </head>
     <body>
       <div id="kyc-widget" style="height: 640px"></div>
       <pre id="status"></pre>
   
       <script src="https://sdk.legitimuz.com/v1/websdk.iife.js"></script>
       <script src="./verification.js"></script>
     </body>
   </html>
   

   A URL v1 do CDN é evergreen: serve sempre a última versão sem breaking change. Não há o que importar, porque não há o que empacotar, o script registra window.Legitimuz.

2. Monte o widget

   verification.js

   // Vem do seu backend. Nunca chumbe uma sdkUrl real aqui: ela carrega a credencial da
   // verificação no fragmento da URL.
   const SDK_URL = "<SUA_SDK_URL>";
   
   const statusEl = document.getElementById("status");
   
   function log(text) {
     statusEl.textContent += `[${new Date().toISOString()}] ${text}\n`;
   }
   
   const handle = window.Legitimuz.mount({
     sdkUrl: SDK_URL,
     target: document.getElementById("kyc-widget"),
     onReady: () => log("ready"),
     onEvent: (event) => log(`event: ${event.type} ${JSON.stringify(event.payload ?? {})}`),
     // "o fluxo terminou", não "deu certo": status é "submitted" ou "abandoned"
     onComplete: (result) => log(`complete: ${result.status}`),
     onCancel: (result) => log(`cancelled: ${result.sessionId ?? "no session"}`),
     // user_message pode ser mostrado ao titular; o resto é para o seu log
     onError: (error) => log(`error ${error.code}: ${error.user_message}`),
   });
   
   // encerra o iframe e a câmera ao sair da página
   window.addEventListener("pagehide", () => handle.destroy());
   
3. Sirva a página

   python3 -m http.server 8080
   

   Abra http://localhost:8080. Cadastre localhost:8080 como origem autorizada da sua integração, é a única origem web que aceita porta. Veja o passo 3.

Confira que funcionou

A primeira tela do fluxo aparece dentro do container e o <pre> recebe ready. A partir daí cada etapa do titular chega como uma linha de event.

O que este caminho prova

• O widget monta num <div> comum, com nada além de window.Legitimuz.mount(...).
• Os cinco callbacks do contrato público disparam e carregam a forma documentada em eventos e tratamento de erros.
• handle.destroy() limpa o iframe e a stream de câmera junto.

Opções da SDK

Ver todas as opções

O SDK é carregado por CDN e registra window.Legitimuz:

const handle = window.Legitimuz.mount(options);

Opções

sdkUrl · string · required

URL emitida pelo servidor da Legitimuz para uma verificação. Precisa ser absoluta e apontar para a origem do widget: qualquer outro valor gera o erro 6004. Trate-a como credencial, sem registrar em log nem enviar para ferramentas de analytics. Veja segurança.

target · HTMLElement · required

Elemento onde o widget renderiza. O iframe ocupa 100% da altura do container, então dê altura a ele. Ausente, o mount() reporta 6003 e nada é montado.

colorScheme · "light" | "dark" | "auto" · default: "auto"

Tema do widget. Com "auto", o SDK resolve para claro ou escuro pela preferência do navegador no momento do mount. Valor inválido gera 6004, mas não bloqueia: o widget abre com o fallback.

locale · string · default: "pt-BR"

Idioma do widget. Sem a opção, pt-BR, o SDK não detecta o idioma do navegador. O widget suporta pt-BR e en, resolve por prefixo (en-US vira en) e cai para pt-BR quando não reconhece o valor.

closeButton · "left" | "right" | "hidden" · default: "right"

Onde o controle de fechar do próprio widget renderiza, ou "hidden" para não renderizar nenhum. Clicar nele pede confirmação ao titular antes de encerrar o fluxo; confirmando, chega ao host como onCancel e o evento session.abandoned, descritos em eventos. O controle fica oculto na etapa final independente do valor. Valor inválido gera 6004, mas não bloqueia: o widget abre com o fallback "right".

iframeTitle · string · default: "Verificação de identidade"

Rótulo acessível do iframe, anunciado por leitores de tela. Sobrescreva quando o contexto da sua página pedir um texto mais específico.

readyTimeoutMs · number · default: "15000"

Quanto esperar pelo sinal ready do widget antes de reportar 6005 via onError. 0 ou Infinity desligam o diagnóstico.

onReady · () => void

O widget carregou e a primeira tela está visível. O mesmo sinal existe em formato aguardável no handle, como a promise ready.

onEvent · (event) => void

Eventos de progresso da sessão. O catálogo completo está em eventos.

eventsAllowlist · string[]

Filtra o que chega em onEvent e no evento DOM legitimuz-event. Sem a opção, tudo passa, inclusive tipos de evento que a sua versão do pacote ainda não conhece. Lista vazia silencia todos os eventos. Não afeta onComplete, onCancel nem onError.

onComplete · (result) => void

O fluxo terminou. result.status é "submitted" ou "abandoned", e terminar não significa aprovado nem concluído com sucesso. Veja eventos.

onCancel · (result) => void

O widget declarou cancelamento, pelo servidor ou porque o titular confirmou a saída no controle closeButton. result.sessionId identifica a sessão, quando disponível. Para retomar, chame mount() de novo; quem resolve o estado é o servidor.

onError · (error) => void

Erros de configuração e do fluxo. O SDK nunca lança exceção: sem onError, os erros vão para console.error. Veja tratamento de erros.

Handle

mount() retorna um handle com dois membros:

destroy() · () => void

Remove o widget da página e encerra a comunicação. Chame ao desmontar a tela.

ready · Promise<void>

Resolve quando o widget sinaliza ready (o mesmo sinal do onReady). Rejeita com o erro 6003 ou 6004 quando a configuração impede criar o iframe, com 6005 quando o ready não chega dentro de readyTimeoutMs, e com DOMException de nome AbortError quando destroy() é chamado antes do ready.

Utilitário: isValidCPF

O pacote exporta um validador de CPF para o formulário que antecede a verificação:

window.Legitimuz.isValidCPF("000.000.000-00"); // false: dígito verificador inválido

Próximo passo

Testar

Rode a jornada ponta a ponta e veja a decisão chegar.