Paquete NPM

El SDK @surtai/faceguard es la forma recomendada de integrar FaceGuard en aplicaciones web. Gestiona automáticamente la creación del iframe, la detección del dispositivo, el mapeo de eventos y la limpieza.

npm install @surtai/faceguard

Estilo con callbacks (FaceGuard.init)

TypeScript

import { FaceGuard } from '@surtai/faceguard';

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onReady: () => console.log('FaceGuard cargado'),
  onSuccess: (result) => {
    console.log('Aprobado', result.confidence);
    // Conceder acceso
  },
  onFailed: (result) => {
    console.log('Rechazado', result.confidence);
    // Denegar acceso o reintentar
  },
  onCancel: () => console.log('Usuario cerró'),
  onError: (error) => console.log('Error', error.message),
});

// Limpiar manualmente si es necesario
fg.destroy();

Estilo async/await (FaceGuard.verify)

TypeScript

import { FaceGuard } from '@surtai/faceguard';

const result = await FaceGuard.verify({ token: 'PORTAL_TOKEN' });

switch (result.status) {
  case 'approved':
    console.log('Verificado', result.confidence);
    break;
  case 'rejected':
    console.log('Fallido', result.confidence);
    break;
  case 'canceled':
    console.log('Usuario cerró');
    break;
  case 'error':
    console.log('Error:', result.error);
    break;
}

Opciones

Opción	Tipo	Requerido	Por defecto	Descripción
token	string	Sí		JWT de portal desde tu backend
baseUrl	string	No	https://faceguard.surt.com	Override para entornos que no sean de producción
mode	'mobile' | 'desktop'	No	Detección automática	Forzar flujo móvil (cámara) o escritorio (QR)
container	HTMLElement	No	document.body	Elemento DOM donde montar el overlay
lang	string	No	Idioma del navegador	'en', 'es', 'pt' o 'de'

Callbacks (FaceGuard.init)

Callback	Payload	Descripción
onReady		iframe de FaceGuard cargado
onSuccess	{ confidence: number }	Verificación aprobada (0-100)
onFailed	{ confidence: number }	Verificación fallida (0-100)
onCancel		Usuario cerró FaceGuard
onError	{ message: string }	Algo salió mal

Resultado (FaceGuard.verify)

interface FaceGuardVerifyResult {
  status: 'approved' | 'rejected' | 'canceled' | 'error';
  confidence?: number;  // 0-100, presente para approved/rejected
  error?: string;       // presente para el estado error
}

Detección de dispositivo

El SDK detecta automáticamente móvil vs escritorio:

• Móvil / Tablet: Abre /intro - flujo de cámara a pantalla completa
• Escritorio: Abre /qrcode - modal con forma de teléfono con código QR + "Verificar aquí"

La detección usa capacidad táctil + tamaño de pantalla + UA hints (detecta iPads en horizontal, tablets Android, etc.). Anula con mode: 'mobile' o mode: 'desktop' si es necesario.

Ejemplos por framework

React

React

import { useEffect, useRef } from 'react';
import { FaceGuard } from '@surtai/faceguard';

function FaceVerification({ token, onResult }) {
  const fgRef = useRef(null);

  useEffect(() => {
    fgRef.current = FaceGuard.init({
      token,
      onSuccess: (result) => onResult('approved', result.confidence),
      onFailed: (result) => onResult('rejected', result.confidence),
      onCancel: () => onResult('canceled'),
      onError: (error) => onResult('error', error.message),
    });

    return () => fgRef.current?.destroy();
  }, [token]);

  return null; // El SDK crea su propio overlay
}

Next.js

Next.js

'use client';

import { useCallback } from 'react';
import { FaceGuard } from '@surtai/faceguard';

export function VerifyButton({ token }: { token: string }) {
  const handleVerify = useCallback(async () => {
    const result = await FaceGuard.verify({ token });
    if (result.status === 'approved') {
      window.location.href = '/dashboard';
    }
  }, [token]);

  return <button onClick={handleVerify}>Verificar identidad</button>;
}

Vue

Vue

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { FaceGuard } from '@surtai/faceguard';

const props = defineProps(['token']);
const emit = defineEmits(['result']);
let fg = null;

onMounted(() => {
  fg = FaceGuard.init({
    token: props.token,
    onSuccess: (r) => emit('result', { status: 'approved', confidence: r.confidence }),
    onFailed: (r) => emit('result', { status: 'rejected', confidence: r.confidence }),
    onCancel: () => emit('result', { status: 'canceled' }),
  });
});

onUnmounted(() => fg?.destroy());
</script>

Entornos

Entorno	baseUrl
Producción	Omitir (por defecto: https://faceguard.surt.com)
QA	'https://qa.faceguard.surt.com'
Staging	'https://staging.faceguard.surt.com'
Dev local	'http://localhost:5173'