@deconve/liveness-3d

Integração Deconve para detecção de liveness 3D. Encapsula autenticação e gerenciamento de sessão contra o backend Deconve.

Instalação

npm install @deconve/liveness-3d

Peer dependencies

npm install react react-dom @aws-amplify/ui-react @aws-amplify/ui-react-liveness

Inclua os estilos no ponto de entrada da aplicação:

import "@aws-amplify/ui-react/styles.css";
import "@aws-amplify/ui-react-liveness/styles.css";

API

getToken(apiKey, authUrl?)

Troca a chave de API por um JWT de acesso.

import { getToken } from "@deconve/liveness-3d";

const token = await getToken("sua-api-key");

useFaceLivenessSession(apiBaseUrl, token)

Hook React que inicia uma sessão de liveness e retorna as credenciais necessárias para o detector.

const { faceLivenessData, faceLivenessLoading, faceLivenessError, createSession } =
  useFaceLivenessSession(apiBaseUrl, token);

| Retorno | Tipo | Descrição | |---|---|---| | faceLivenessData | FaceLivenessData \| null | Dados da sessão ativa | | faceLivenessLoading | boolean | true enquanto a sessão está sendo criada | | faceLivenessError | unknown | Erro da requisição, se houver | | createSession | () => Promise<void> | Recria a sessão manualmente |

createLivenessSession(apiBaseUrl, token)

Versão imperativa (sem hook) de criação de sessão.

const data: FaceLivenessData = await createLivenessSession(apiBaseUrl, token);

finishLivenessSession(livenessSessionId, apiBaseUrl, token)

Finaliza a sessão e retorna o resultado da verificação.

const result: FinishResponse = await finishLivenessSession(
  faceLivenessData.livenessSessionId,
  apiBaseUrl,
  token
);

console.log(result.isLive);  // true | false
console.log(result.status);  // detalhe opcional
console.log(result.image);   // frame capturado em base64, se disponível

Tipos

interface FaceLivenessData {
  livenessSessionId: string;
  accessCredentials: AccessCredentials;
}

interface AccessCredentials {
  accessKeyId: string;
  secretAccessKey: string;
  sessionToken: string;
}

interface FinishResponse {
  isLive: boolean;
  status?: string;
  image?: string;
}

Exemplo de uso

import { useState, useEffect } from "react";
import {
  getToken,
  useFaceLivenessSession,
  finishLivenessSession,
  FaceLivenessDetectorCore,
  type FinishResponse,
} from "@deconve/liveness-3d";

const API_URL = "https://api.deconve.com";

interface Props {
  apiKey: string;
  onResult: (result: FinishResponse) => void;
}

export function LivenessCapture({ apiKey, onResult }: Props) {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    getToken(apiKey).then(setToken);
  }, [apiKey]);

  const { faceLivenessData, faceLivenessLoading, faceLivenessError, createSession } =
    useFaceLivenessSession(API_URL, token ?? "");

  if (!token || faceLivenessLoading) return <p>Iniciando sessão...</p>;

  if (faceLivenessError) {
    return (
      <div>
        <p>Não foi possível iniciar a sessão.</p>
        <button onClick={createSession}>Tentar novamente</button>
      </div>
    );
  }

  const handleAnalysisComplete = async () => {
    const result = await finishLivenessSession(
      faceLivenessData!.livenessSessionId,
      API_URL,
      token
    );
    onResult(result);
  };

  return (
    <FaceLivenessDetectorCore
      sessionId={faceLivenessData?.livenessSessionId ?? ""}
      region="us-east-1"
      onAnalysisComplete={handleAnalysisComplete}
      onError={createSession}
      onUserCancel={createSession}
      config={{
        credentialProvider: async () => faceLivenessData!.accessCredentials,
      }}
    />
  );
}

Build

npm install
npm run build   # gera dist/
npm run dev     # watch mode