Integração Web

Guia para integrar o SDK de digitais em aplicações web.

Opção 1: Usar a API diretamente

A forma mais simples é enviar imagens via fetch para a API.

async function processFingerprint(imageFile: File) {
  const formData = new FormData();
  formData.append("file", imageFile);

  const response = await fetch("https://sdk-demo.valid.ia.br/api/process", {
    method: "POST",
    body: formData,
  });

  const result = await response.json();

  if (result.success) {
    // result.image_base64 contém a imagem processada em PNG/base64
    const imgSrc = `data:image/png;base64,${result.image_base64}`;
    // result.quality_score contém o score (0-100)
    // result.quality contém métricas detalhadas
  } else {
    // result.error contém a mensagem de erro
  }
}

Opção 2: Com preview de posicionamento

Para guiar o usuário em tempo real, use o pacote @valid/finger-preview.

Setup

<!-- Carregar opencv.js (necessário para detecção de pele) -->
<script src="https://docs.opencv.org/4.x/opencv.js" async></script>

import { FingerPreview } from "@valid/finger-preview";

const video = document.querySelector("video");
const canvas = document.querySelector("canvas");

// Iniciar câmera
const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: "environment", width: 640, height: 480 },
});
video.srcObject = stream;

// Iniciar preview
const preview = new FingerPreview(video, canvas, {
  guideColor: "#00ff88",
  targetFps: 15,
}, {
  onMessage: (type, text) => {
    // type: "position" | "closer" | "hold" | "ready"
    document.getElementById("message").textContent = text;
  },
  onReady: () => {
    // opencv.js carregou, preview ativo
  },
});

preview.start();

// Quando quiser capturar
const blob = captureVideoFrame(video);
preview.stop();
await processFingerprint(blob);

Fluxo Recomendado

1. Abrir câmera (traseira preferível)
2. Mostrar preview com guia de posicionamento
3. Aguardar mensagem "ready" (dedo posicionado corretamente)
4. Capturar frame
5. Enviar para API
6. Mostrar resultado + métricas de qualidade
7. Se qualidade baixa, permitir nova captura

React — Exemplo Completo

import { useState } from "react";

function FingerprintCapture() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setLoading(true);
    try {
      const formData = new FormData();
      formData.append("file", file);

      const res = await fetch("/api/process", {
        method: "POST",
        body: formData,
      });
      setResult(await res.json());
    } catch (err) {
      console.error("Erro:", err);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={handleFile} />
      {loading && <p>Processando...</p>}
      {result?.success && (
        <div>
          <img src={`data:image/png;base64,${result.image_base64}`} />
          <p>Qualidade: {result.quality_score.toFixed(1)}/100</p>
        </div>
      )}
      {result?.error && <p style={{ color: "red" }}>{result.error}</p>}
    </div>
  );
}

Dicas

• Câmera traseira dá melhores resultados que a frontal
• Iluminação é crucial — evitar sombras fortes e contraluz
• Distância ideal: dedo ocupando ~30-50% do frame
• Foco automático geralmente funciona bem, mas foco manual em macro é ideal
• O preview JS/WASM roda ~15fps e consome pouca CPU

CORS

Se a API está em um domínio diferente, configure FINGERPRINT_CORS_ORIGINS:

FINGERPRINT_CORS_ORIGINS=["https://seu-app.com"]