Remix

Monte o widget num app Remix ou React Router 7, com a credencial emitida por uma action de servidor.

Ao final deste guia o fluxo de verificação abre num app Remix, com a credencial vinda de uma action de servidor e o widget montando no cliente.

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

   Declare o script no root.tsx, antes dos scripts do app.

   app/root.tsx

   import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";
   
   export default function Root() {
     return (
       <html lang="pt-BR">
         <head>
           <Meta />
           <Links />
           <script src="https://sdk.legitimuz.com/v1/websdk.iife.js" />
         </head>
         <body>
           <Outlet />
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }
   
2. Declare o global

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

3. Emita a credencial no loader

   app/routes/verification.tsx

   import { useLoaderData } from "react-router";
   import { useLegitimuz } from "~/hooks/useLegitimuz";
   
   export async function loader({ request }: { request: Request }) {
     const user = await authenticate(request);
     const registration = await db.registration.byUser(user.id);
   
     const response = await fetch("https://api-core.legitimuz.com/public/verifications", {
       method: "POST",
       headers: {
         "X-API-Key": process.env.LEGITIMUZ_API_KEY!,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         schema_version: "1.0",
         ref_id: registration.id,
         document: { type: "cpf", number: registration.cpf },
       }),
     });
   
     const { verification, entry } = await response.json();
     await db.registration.link(registration.id, verification.public_id);
     return { sdkUrl: entry.url as string };
   }
   
   export default function Verification() {
     const { sdkUrl } = useLoaderData<typeof loader>();
     const { containerRef, status } = useLegitimuz({ sdkUrl });
   
     return (
       <>
         <div ref={containerRef} style={{ height: 640 }} />
         <p>{status}</p>
       </>
     );
   }
   

   O loader roda só no servidor. A chave nunca chega ao bundle do cliente.

   O hook useLegitimuz é o mesmo do guia de React: monta uma vez por sdkUrl e chama destroy() no cleanup.

Confira que funcionou

A primeira tela aparece dentro do container e o status vira pronto.

Boas práticas

Loader no servidor, montagem no cliente

O loader entrega só a sdkUrl ao componente. O useEffect do hook roda no browser, onde window.Legitimuz já existe porque o script está no root.tsx.

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.