Eventos

O catálogo de eventos do Web SDK, os payloads e o desfecho do fluxo.

O widget reporta o progresso da sessão em eventos, entregues ao callback onEvent do mount():

mount({
  sdkUrl: "<SUA_SDK_URL>",
  target: document.querySelector("#verificacao"),
  onEvent: (event) => {
    // event.type: string · event.payload?: objeto
  },
});

Eventos são telemetria: use-os para analytics e para reagir na sua interface. O fim do fluxo não chega por aqui, e sim por onComplete e onCancel, descritos abaixo.

Catálogo

Evento	Quando dispara	Payload
session.started	O fluxo abriu a primeira etapa	—
session.stepTransitioned	O servidor trocou a etapa	from, to
document.capture.started	O titular começou a capturar um lado do documento	side
document.capture.completed	A captura do documento foi enviada	side
document.capture.failed	A captura do documento falhou	side, code
selfie.capture.started	A captura facial começou	—
selfie.capture.completed	A captura facial terminou	—
liveness.completed	A prova de vida foi concluída	—
liveness.failed	A prova de vida falhou	code
session.completed	O fluxo terminou	status
session.error	Um erro ocorreu na sessão	code, recoverable
session.abandoned	O titular confirmou a saída no controle closeButton	—
decision.notified	Reservado; o widget ainda não emite	—
terms.open	O widget pediu para abrir os termos de uso	url
redirect.open	O widget pediu um redirect pós-fluxo	url

Os campos from e to carregam identificadores de etapa: são rótulos de telemetria, não um contrato para ramificar comportamento. Os campos code carregam um código de erro.

O SDK abre terms.open e redirect.open sozinho, numa aba nova (window.open(url, "_blank", "noopener,noreferrer")), deduplicando cliques repetidos na mesma URL dentro de 1 segundo — o iframe não pode abrir popup nem navegar a sua página por conta própria. Não há como substituir essa abertura; o evento chega ao onEvent de qualquer forma, para quem só quer observar.

Modelo evergreen

O widget pode emitir tipos de evento que a sua versão do pacote ainda não conhece: eles passam pelo onEvent normalmente, em vez de serem descartados. Se você liga o onEvent direto num pipeline de analytics e não quer cardinalidade nova aparecendo sozinha, congele o conjunto com eventsAllowlist.

eventsAllowlist: [] silencia todos os eventos. Lista vazia significa que nada passa; para deixar tudo passar, omita a opção.

Desfecho do fluxo

O desfecho chega por dois callbacks próprios, fora do catálogo de eventos. onComplete dispara quando o widget declara fim de fluxo: result.status é "submitted" (o titular enviou tudo) ou "abandoned" (o fluxo terminou sem envio). onCancel dispara quando o widget declara cancelamento — pelo servidor ou porque o titular confirmou a saída no controle closeButton —, e result.sessionId identifica a sessão quando disponível. Esse mesmo cancelamento pelo titular também chega como o evento session.abandoned no onEvent, para quem só acompanha telemetria.

Terminar não é ser aprovado: a decisão da verificação chega ao seu backend, nunca ao navegador. E a régua entre os dois callbacks é a origem da declaração, não o resultado, então um abandono pode chegar pelos dois canais. Antes de contabilizar conversão, cheque sempre result.status. Contar "abandoned" como sucesso infla a métrica.

Eventos DOM

Cada sinal também é despachado como CustomEvent no elemento <legitimuz-websdk> que o mount() cria. É útil em HTML puro e em frameworks que escutam eventos direto no template:

Evento DOM	Equivalente
legitimuz-ready	onReady
legitimuz-event	onEvent
legitimuz-complete	onComplete
legitimuz-cancel	onCancel
legitimuz-error	onError

const widget = document.querySelector("legitimuz-websdk");

widget.addEventListener("legitimuz-event", (event) => {
  console.log(event.detail.type);
});

Os eventos não borbulham e não atravessam shadow DOM: escute no próprio elemento.