Next.js

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.

Monte o fluxo

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.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.

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.

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.

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.

Guia rápido

Desenvolvedores

Web

SDKs

Pré-requisitos

Monte o fluxo

Confira que funcionou

Boas práticas

Carregue o SDK com beforeInteractive

Próximo passo

React

Receber a decisão

​Pré-requisitos

​Monte o fluxo

​Confira que funcionou

​Boas práticas

Carregue o SDK com beforeInteractive

​Próximo passo

React

Receber a decisão

Pré-requisitos

Monte o fluxo

Confira que funcionou

Boas práticas

Próximo passo