Next.js

Monte o widget no App Router mantendo a página como Server Component e o SDK carregado a tempo.

Ao final deste guia o fluxo de verificação abre num app Next.js com App Router, com a página permanecendo Server Component.

O App Router renderiza no servidor, onde window não existe. Duas coisas resolvem isso, e a segunda é a que costuma passar despercebida.

Pré-requisitos

• Node.js 20 ou superior.
• Uma sdkUrl emitida pelo seu backend, como em emitir a credencial.
• O guia de React, o hook é o mesmo, e a declaração de tipos também.

Confira o exemplo

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

Monte o fluxo

1. Carregue o SDK no layout

   app/layout.tsx

   import Script from "next/script";
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html lang="pt-BR">
         <body>
           {children}
           <Script src="https://sdk.legitimuz.com/v1/websdk.iife.js" strategy="beforeInteractive" />
         </body>
       </html>
     );
   }
   

   beforeInteractive só é aceito em app/layout.tsx, e é o que garante que window.Legitimuz existe antes de qualquer efeito de componente cliente rodar. Veja as boas práticas abaixo.

2. Isole o widget num Client Component

   components/VerificationWidget.tsx

   "use client";
   
   import { useEffect, useRef } from "react";
   
   export function VerificationWidget({ sdkUrl }: { sdkUrl: string }) {
     const containerRef = useRef<HTMLDivElement | null>(null);
   
     useEffect(() => {
       if (!containerRef.current) return;
       const handle = window.Legitimuz.mount({ sdkUrl, target: containerRef.current });
       return () => handle.destroy();
     }, [sdkUrl]);
   
     return <div ref={containerRef} style={{ height: 640 }} />;
   }
   

   O "use client" precisa ser a primeira linha do arquivo: um prólogo de diretiva não pode vir depois de um comentário. Sem ele, este componente tentaria rodar na renderização do servidor, onde window não existe.

3. Mantenha a página no servidor

   app/page.tsx

   import { VerificationWidget } from "@/components/VerificationWidget";
   
   export default function Page() {
     return (
       <main>
         <VerificationWidget sdkUrl={process.env.NEXT_PUBLIC_LEGITIMUZ_SDK_URL!} />
       </main>
     );
   }
   

   Sem "use client" aqui. A página continua Server Component e passa a sdkUrl como prop, como faria com qualquer outro filho.

4. Configure a sdkUrl

   .env.local

   NEXT_PUBLIC_LEGITIMUZ_SDK_URL=<SUA_SDK_URL>
   

   O prefixo NEXT_PUBLIC_ é obrigatório: o valor precisa chegar ao navegador, e process.env.LEGITIMUZ_SDK_URL sem prefixo seria undefined no componente cliente.

   Numa integração real, a sdkUrl não vem de variável de ambiente, ela é emitida por verificação. Busque-a num Server Component ou numa Route Handler e passe como prop.

Confira que funcionou

A primeira tela aparece dentro do container. No console do servidor não deve haver nenhum erro de window is not defined.

Boas práticas

Carregue o SDK com beforeInteractive

A estratégia beforeInteractive garante que window.Legitimuz exista antes de qualquer efeito de componente cliente rodar. É a forma recomendada para este script.

Se a sua arquitetura pede afterInteractive, condicione a montagem a um estado que o onLoad do <Script> ativa. Assim o widget só monta quando o SDK estiver disponível.

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

React

O hook completo, com tipos e o cuidado com o StrictMode.

Receber a decisão

Onde o desfecho realmente chega.