MetaG SDK React 🔐

Componente React de captura de rostro para autenticación biométrica con validación encriptada mediante MetaG API.

✨ Características

• 📸 Captura de rostro en tiempo real - Acceso a cámara web con vista previa en vivo
• 🔐 Encriptación integrada - Validación segura de datos con crypto-js
• 📱 Responsive Design - Compatible con dispositivos móviles y escritorio
• 🎯 Validación inteligente - Reconocimiento facial automático y modal de errores
• ⚡ Sin dependencias extras - Solo React como peer dependency
• 📦 TypeScript - Tipos completos para mejor experiencia de desarrollo
• 🎨 Estilos incluidos - CSS moderno y personalizable
• 🔄 Zoom ajustable - Control de zoom de cámara nativa cuando está disponible

📦 Instalación

npm install @fundaciongenesisempresarial/sdk-metag-react

o con yarn:

yarn add @fundaciongenesisempresarial/sdk-metag-react

o con pnpm:

pnpm add @fundaciongenesisempresarial/sdk-metag-react

🚀 Uso rápido

import { FaceCapture } from '@fundaciongenesisempresarial/sdk-metag-react';
import '@fundaciongenesisempresarial/sdk-metag-react/styles';

function App() {
  const handleComplete = (result) => {
    console.log('Captura completada:', result);
  };

  return (
    <FaceCapture
      apiKey="tu-api-key"
      connection="tu-connection"
      identificador="id-usuario"
      env="production"
      onComplete={handleComplete}
    />
  );
}

export default App;

📋 Props Requeridas

| Prop | Tipo | Requerido | Descripción | Default | |------|------|----------|-------------|---------| | apiKey | string | ✅ | Clave API para autenticación | - | | connection | string | ✅ | ID de conexión | - | | identificador | string | ✅ | Identificador único del usuario | - | | env | string | ✅ | Ambiente (production, development, etc.) | - |

📋 Props Opcionales

| Prop | Tipo | Requerido | Descripción | Default | |------|------|----------|-------------|---------| | onCancel | () => void | ❌ | Callback al cancelar | - | | onComplete | (result) => void | ❌ | Callback al completar captura | - | | brand | string | ❌ | Nombre de marca a mostrar | "MetaG" | | title | string | ❌ | Título personalizado | - | | subtitle | string | ❌ | Subtítulo personalizado | - | | captureLabel | string | ❌ | Texto del botón de captura | "Capturar" | | className | string | ❌ | Clases CSS adicionales | - |

💬 Respuesta de Callback

onComplete

{
  completed: true,
  datos: {
    CUI: string;
    PRIMER_NOMBRE: string;
    SEGUNDO_NOMBRE?: string;
    PRIMER_APELLIDO: string;
    SEGUNDO_APELLIDO?: string;
    // ... más campos según API
  }
}

onCancel

() => void

onCancel se ejecuta cuando el usuario cierra el flujo (boton X). Este callback no envia parametros; se usa para notificar a tu app que el proceso fue cancelado.

🎨 Personalización

Usando clases CSS

<FaceCapture
  {...props}
  className="mi-contenedor-personalizado"
/>

Importar solo estilos

import '@fundaciongenesisempresarial/sdk-metag-react/styles';

Sobrescribir estilos CSS

.face-capture {
  --primary-color: #007bff;
  --text-color: #333;
  --border-color: #ddd;
}

.fc-header {
  background-color: #f5f5f5;
}

🔐 Flujo de Autenticación

1. Inicialización → Se valida apiKey, connection e identificador
2. Obtención de Ambiente → Se obtiene la URL base según env
3. Inicialización de Proceso → Se genera un nuevo proceso
4. Captura de Selfie → Se obtiene imagen capturada por la camara
5. Validación Encriptada → Se valida la selfie de forma segura contra la API
6. Proceso Completado → Se retorna resultado con datos

⚙️ Requisitos del Sistema

• React 18.x o 19.x
• Navegador con soporte para getUserMedia API
• HTTPS en producción (requerido por navegadores modernos)

🌐 Compatibilidad

| Navegador | Versión | Soporte | |-----------|---------|--------| | Chrome | 59+ | ✅ | | Firefox | 55+ | ✅ | | Safari | 11+ | ✅ | | Edge | 79+ | ✅ | | Opera | 46+ | ✅ |

🐛 Manejo de Errores

El componente maneja automáticamente:

• ❌ Permisos de cámara denegados
• ❌ Dispositivo sin cámara
• ❌ Errores de encriptación
• ❌ Fallos en validación
• ❌ Errores de conexión API

Los errores se muestran en modal ValidationErrorModal con opción de reintentar.

📝 Ejemplo Completo

import { useState } from 'react';
import { FaceCapture, type InitProcessPersonData } from '@fundaciongenesisempresarial/sdk-metag-react';
import '@fundaciongenesisempresarial/sdk-metag-react/styles';

function AuthenticationFlow() {
  const [isCapturing, setIsCapturing] = useState(true);
  const [userData, setUserData] = useState<InitProcessPersonData | null>(null);

  const handleComplete = (result: { completed: true; datos: InitProcessPersonData | null }) => {
    if (result.datos) {
      setUserData(result.datos);
      setIsCapturing(false);
      console.log('✅ Autenticación exitosa:', result.datos);
    }
  };

  const handleCancel = () => {
    setIsCapturing(false);
    console.log('❌ Autenticación cancelada');
  };

  if (!isCapturing && userData) {
    return (
      <div>
        <h1>¡Bienvenido!</h1>
        <p>CUI: {userData.CUI}</p>
        <p>Nombre: {userData.PRIMER_NOMBRE} {userData.PRIMER_APELLIDO}</p>
      </div>
    );
  }

  return (
    <FaceCapture
      apiKey={import.meta.env.VITE_METAG_API_KEY}
      connection={import.meta.env.VITE_METAG_CONNECTION}
      identificador={import.meta.env.VITE_USER_ID}
      env={import.meta.env.VITE_METAG_ENV || 'production'}
      brand="Mi Aplicación"
      onComplete={handleComplete}
      onCancel={handleCancel}
    />
  );
}

export default AuthenticationFlow;

📚 Documentación Adicional

• API Reference
• Troubleshooting
• Contributing

📄 Licencia

MIT © Genesis Empresarial

🙏 Soporte

¿Tienes preguntas o necesitas ayuda?

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Desarrollado con ❤️ por Genesis Empresarial