Documentação

Componentes

Dois componentes cobrem os três fluxos de verificação. Ambos aceitam as mesmas props de callback e tela de resultado.

LivenessCheck

Prova de vida isolada. O usuário passa pelo detector de liveness e o SDK retorna se a captura foi aprovada. O JSON de onResult inclui selfieBase64 (frame capturado no navegador, anexado no frontend).

"use client";
import { LivenessCheck } from "techface-sdk";

<LivenessCheck
  onResult={(result) => console.log(result)}
  onError={(error) => console.error(error.code, error.message)}
/>

FaceMatchCheck

Comparação facial com ou sem liveness. Exige uma imagem de referência via URL pública ou base64.

Com prova de vida (padrão)

<FaceMatchCheck
  liveness
  referenceImage={{ url: "https://exemplo.com/foto-documento.jpg" }}
  onResult={(result) => console.log(result.approved)}
  onError={(error) => console.error(error.message)}
/>

Sem prova de vida — selfie + comparação

<FaceMatchCheck
  liveness={false}
  referenceImage={{ base64: "<conteudo-base64-da-foto>" }}
  onResult={(result) => console.log(result.faceMatch?.similarity)}
/>

Nos três fluxos, selfieBase64 pode aparecer no onResult. Nos fluxos com liveness, a imagem é capturada e anexada no frontend — a API não devolve a foto. No fluxo facematch (sem liveness), a selfie também é enviada à API para comparação, mas o campo no JSON continua vindo do cliente. Veja Resultado e erros.

Props compartilhadas

Aplicam-se a LivenessCheck e FaceMatchCheck:

Prop	Tipo	Descrição
`onResult`	`(result) => void`	Callback com o resultado consolidado em JSON.
`onError`	`(error) => void`	Erros com `code` e `message` em pt-BR.
`id`	`string`	Identificador opcional do fluxo. Necessário para `useTechfaceReset(id)` com UI customizada. Use um id único por verificador na mesma tela.
`showResultScreen`	`boolean`	Exibe a tela de resultado do SDK. Padrão: `true`.
`resultFields`	`ResultField[]`	Quais detalhes exibir na tela de resultado. Padrão: todos. Não altera o JSON de `onResult`. Guia completo em Resultado → resultFields.
`onReady`	`(api) => void`	Recebe `{ reset }` ao montar. Alternativa a `useTechfaceReset` / `ref`.

Personalizar detalhes da tela — `resultFields`

Filtra as linhas da ResultScreen sem esconder o título nem o botão de retry. O callback onResult continua com o JSON completo.

// Só métricas de liveness
<LivenessCheck
  resultFields={["liveness", "livenessConfidence"]}
  onResult={(result) => console.log(result)}
/>

// Face match: tipo + similaridade
<FaceMatchCheck
  liveness
  referenceImage={{ url: "https://exemplo.com/documento.jpg" }}
  resultFields={["type", "faceMatch", "similarity"]}
  onResult={(result) => console.log(result)}
/>

// Só título aprovado/reprovado
<LivenessCheck resultFields={[]} onResult={(result) => console.log(result)} />

Tabela de campos e uso com ResultScreen avulsa: Resultado e erros.

UI customizada — `useTechfaceReset(id)`

Com showResultScreen={false}, passe o mesmo id no componente e no hook. Mantenha o componente montado (pode ocultar com CSS). Não precisa de ref nem key.

const reset = useTechfaceReset("verificacao");
const [result, setResult] = useState<VerificationResult | null>(null);

return (
  <>
    <div style={{ display: result ? "none" : "block" }}>
      <LivenessCheck
        id="verificacao"
        showResultScreen={false}
        onResult={setResult}
      />
    </div>

    {result && (
      <button
        type="button"
        onClick={() => {
          setResult(null);
          reset();
        }}
      >
        Tentar novamente
      </button>
    )}
  </>
);

Com mais de um verificador na tela, use um id por componente e um hook para cada:

const resetLiveness = useTechfaceReset("liveness");
const resetMatch = useTechfaceReset("facematch");

<LivenessCheck id="liveness" showResultScreen={false} ... />
<FaceMatchCheck id="facematch" showResultScreen={false} ... />

Alternativas ao hook: prop onReady={(api) => …} ou ref com ref.current.reset(). Com a tela de resultado padrão do SDK, o botão "Tentar novamente" já reinicia o fluxo — o hook não é necessário.

Props do FaceMatchCheck

Prop	Tipo	Descrição
`referenceImage`	`{ url } \| { base64 }`	Obrigatória. Foto de referência (documento, cadastro anterior, etc.).
`liveness`	`boolean`	Ativa prova de vida antes da comparação. Padrão: `true`.

Exemplo completo

VerificacaoIdentidade.tsx

"use client";

import "techface-sdk/styles.css";
import {
  Techface,
  FaceMatchCheck,
  type VerificationResult,
  type TechfaceError,
} from "techface-sdk";

Techface.configure({ apiKey: process.env.NEXT_PUBLIC_TECHFACE_API_KEY! });

function handleResult(result: VerificationResult) {
  if (result.approved) {
    // prossiga no fluxo do seu produto
  }
  // result.selfieBase64 — JPEG base64 capturado no frontend
  if (result.selfieBase64) {
    // persistir ou enviar ao seu backend
  }
}

function handleError(error: TechfaceError) {
  console.error(error.code, error.message);
}

export function VerificacaoIdentidade() {
  return (
    <FaceMatchCheck
      liveness
      referenceImage={{ url: "https://exemplo.com/documento.jpg" }}
      onResult={handleResult}
      onError={handleError}
      showResultScreen
    />
  );
}