Opções do mount()

Referência completa das opções do mount() do Web SDK, com os valores default.

import { mount } from "@legitimuz/websdk";

const handle = mount(options);

Pelo CDN, a mesma função está em 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.

O 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:

import { isValidCPF } from "@legitimuz/websdk";

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

Quem quer só o validador, sem o widget, importa do subpath @legitimuz/websdk/cpf.