React

Monte o widget num app React com um hook que sobrevive ao double-invoke do StrictMode.

Ao final deste guia o fluxo de verificação abre num app React, montando uma única vez por sdkUrl mesmo em desenvolvimento.

O mount() é imperativo de propósito, então o único lugar onde ele cabe num app React é dentro de um efeito. É uma porta estreita, e é fácil de errar exatamente do jeito que o modo de desenvolvimento do React foi feito para pegar: o <StrictMode> invoca cada efeito duas vezes, e uma montagem que não é idempotente monta o widget duas vezes ou destrói a sessão que acabou de criar.

Pré-requisitos

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

O wrapper @legitimuz/websdk-react, com useLegitimuz e <LegitimuzWidget />, publica no npm no lançamento. O hook abaixo tem a mesma forma, então trocar por um import é mudança de uma linha.

Confira o exemplo

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

Monte o fluxo

1. Carregue o SDK

   index.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. Declare o que você usa:

   src/legitimuz.d.ts

   export interface WebSdkEvent {
     type: string;
     payload?: Record<string, unknown>;
   }
   export interface WebSdkCompleteResult {
     status: "submitted" | "abandoned";
   }
   export interface WebSdkCancelResult {
     sessionId?: string;
   }
   export interface WebSdkError {
     code: number;
     name: string;
     type: string;
     message: string;
     user_message: string;
     context?: Record<string, unknown>;
     doc_url?: string;
     recoverable: boolean;
   }
   export interface LegitimuzWidgetHandle {
     destroy(): void;
     readonly ready: Promise<void>;
   }
   export interface MountOptions {
     sdkUrl: string;
     target: HTMLElement;
     colorScheme?: "light" | "dark" | "auto";
     presentation?: "modal" | "inline";
     locale?: string;
     closeButton?: "left" | "right" | "hidden";
     iframeTitle?: string;
     readyTimeoutMs?: number;
     onReady?: () => void;
     onEvent?: (event: WebSdkEvent) => void;
     /** Filtro opt-in do onEvent. Ausente, tudo passa. Não afeta onComplete/onCancel/onError. */
     eventsAllowlist?: readonly string[];
     onComplete?: (result: WebSdkCompleteResult) => void;
     onCancel?: (result: WebSdkCancelResult) => void;
     onError?: (error: WebSdkError) => void;
   }
   
   declare global {
     interface Window {
       Legitimuz: { mount(options: MountOptions): LegitimuzWidgetHandle };
     }
   }
   
3. Escreva o hook

   src/useLegitimuz.ts

   import { useEffect, useRef } from "react";
   import type { LegitimuzWidgetHandle, MountOptions } from "./legitimuz";
   
   export type UseLegitimuzOptions = Omit<MountOptions, "target">;
   
   export function useLegitimuz(options: UseLegitimuzOptions) {
     const containerRef = useRef<HTMLDivElement | null>(null);
     const handleRef = useRef<LegitimuzWidgetHandle | null>(null);
   
     useEffect(() => {
       if (!containerRef.current) return;
   
       handleRef.current = window.Legitimuz.mount({
         ...options,
         target: containerRef.current,
       });
   
       // Roda uma vez por montagem real, incluindo o primeiro passe descartado do StrictMode
       // em dev. Sem isto, a câmera do widget sobrevive ao unmount que deveria encerrá-la.
       return () => handleRef.current?.destroy();
       // sdkUrl apenas: remontar a cada mudança de opção mataria a sessão em andamento
     }, [options.sdkUrl]);
   
     return containerRef;
   }
   
4. Use no componente

   src/VerificationWidget.tsx

   import { useLegitimuz, type UseLegitimuzOptions } from "./useLegitimuz";
   
   export function VerificationWidget(props: UseLegitimuzOptions) {
     const containerRef = useLegitimuz(props);
     return <div ref={containerRef} style={{ height: 640 }} />;
   }
   

   src/App.tsx

   import { useState } from "react";
   import { VerificationWidget } from "./VerificationWidget";
   import type { WebSdkCompleteResult, WebSdkError, WebSdkEvent } from "./legitimuz";
   
   const sdkUrl = import.meta.env.VITE_LEGITIMUZ_SDK_URL as string;
   
   export default function App() {
     const [status, setStatus] = useState("mounting");
     const [log, setLog] = useState<string[]>([]);
     const append = (line: string) => setLog((entries) => [...entries, line]);
   
     return (
       <>
         <VerificationWidget
           sdkUrl={sdkUrl}
           onReady={() => setStatus("ready")}
           onEvent={(event: WebSdkEvent) => append(event.type)}
           onComplete={(result: WebSdkCompleteResult) => setStatus(`done: ${result.status}`)}
           onCancel={() => setStatus("cancelled")}
           onError={(error: WebSdkError) => setStatus(`error ${error.code}`)}
         />
         <p>{status}</p>
         <ul>{log.map((entry, i) => <li key={i}>{entry}</li>)}</ul>
       </>
     );
   }
   
5. Configure a sdkUrl

   .env

   VITE_LEGITIMUZ_SDK_URL=<SUA_SDK_URL>
   

   O .env fica fora do controle de versão. A sdkUrl carrega a credencial da verificação no fragmento, nunca comite um valor real.

Confira que funcionou

A primeira tela aparece e o status vira pronto. Em desenvolvimento, com <StrictMode> ligado, o widget aparece uma vez. Se aparecerem dois iframes, confira se o destroy() do cleanup está sendo chamado.

Boas práticas

Dependa da sdkUrl, não do objeto de opções

O array de dependências do efeito é [options.sdkUrl]. Assim o widget monta uma vez por sessão e permanece estável entre renders, mesmo quando o objeto de opções é recriado pelo componente pai.

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

Next.js

O mesmo hook, com o cuidado extra que o App Router exige.