Svelte

Monte o widget num app Svelte ou SvelteKit, com o ciclo de vida preso ao componente.

Ao final deste guia o fluxo de verificação abre num app Svelte 5, montando quando o componente entra na tela e encerrando quando ele sai.

Pré-requisitos

• Node.js 20 ou superior.
• Uma sdkUrl emitida pelo seu backend, como em emitir a credencial.

Confira o exemplo

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

Monte o fluxo

1. Carregue o SDK

   No SvelteKit, o script entra no app.html. Em Svelte puro, no index.html.

   src/app.html

   <script src="https://sdk.legitimuz.com/v1/websdk.iife.js"></script>
   

   Antes do bundle. O script registra window.Legitimuz.

2. Declare o global

   O build de CDN não traz tipos. Reaproveite a declaração do guia de React; ela é a mesma.

3. Escreva o componente

   src/lib/VerificationWidget.svelte

   <script lang="ts">
     import { onMount } from "svelte";
     import type { LegitimuzWidgetHandle, WebSdkEvent } from "$lib/legitimuz";
   
     let { sdkUrl }: { sdkUrl: string } = $props();
   
     let container: HTMLDivElement;
     let log = $state<string[]>([]);
   
     onMount(() => {
       const handle: LegitimuzWidgetHandle = window.Legitimuz.mount({
         sdkUrl,
         target: container,
         onReady: () => log.push("ready"),
         onEvent: (event: WebSdkEvent) => log.push(`event: ${event.type}`),
         // "o fluxo terminou", não "deu certo". O desfecho chega pelo webhook.
         onComplete: (result) => log.push(`complete: ${result.status}`),
         onError: (error) => log.push(`error ${error.code}`),
       });
   
       return () => handle.destroy();
     });
   </script>
   
   <div bind:this={container} style="height: 640px"></div>
   <pre>{log.join("\n")}</pre>
   

   O retorno do onMount roda no desmonte e chama destroy(), que encerra a câmera.

4. Passe a sdkUrl pela rota

   No SvelteKit, a credencial vem do servidor pelo load. Assim ela nunca fica no bundle.

   src/routes/verification/+page.server.ts

   import type { PageServerLoad } from "./$types";
   
   export const load: PageServerLoad = async ({ fetch }) => {
     const response = await fetch("/api/verifications", { method: "POST" });
     const { entry } = await response.json();
     return { sdkUrl: entry.url };
   };
   

   src/routes/verification/+page.svelte

   <script lang="ts">
     import VerificationWidget from "$lib/VerificationWidget.svelte";
     let { data } = $props();
   </script>
   
   <VerificationWidget sdkUrl={data.sdkUrl} />
   

Confira que funcionou

A primeira tela aparece dentro do container e o <pre> recebe ready. Ao navegar para outra rota, o indicador de câmera do browser apaga.

Boas práticas

Monte no cliente, emita no servidor

onMount só roda no browser, então window.Legitimuz está disponível quando o componente monta. A sdkUrl vem do load do servidor, e a chave de API fica só lá.

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.