MetaG Flutter SDK

SDK oficial de Flutter para integrar los servicios de verificación de identidad biométrica de la plataforma MetaG en aplicaciones móviles.

Características Principales

🎯 Verificación de Identidad Completa

📸 Captura de documento de identidad (frontal y reverso)
🎥 Video selfie para validación biométrica
📷 Captura de foto biométrica
✅ Flujo guiado paso a paso
🔐 Integración segura con API de MetaG
📱 Diseño responsive y Material Design 3

🛠️ Características Técnicas

Gestión automática de tokens biométricos
Callbacks con resultados detallados
Manejo de errores robusto
Interfaz de usuario personalizable
Soporte para múltiples ambientes (QA, Producción)
Validación en tiempo real

Instalación

Desde pub.dev (Recomendado)

Ejecuta el siguiente comando en la raíz de tu proyecto:

flutter pub add metag_flutter_sdk

O agrega manualmente el SDK a tu archivo pubspec.yaml:

dependencies:
  metag_flutter_sdk: ^1.0.0

Luego ejecuta:

flutter pub get

📦 Paquete oficial: https://pub.dev/packages/metag_flutter_sdk

Instalación Local (Desarrollo)

Si estás desarrollando o necesitas una versión local:

dependencies:
  metag_flutter_sdk:
    path: ../metag_flutter_sdk

Permisos de Cámara

El SDK utiliza la cámara del dispositivo para la verificación de identidad. Debes configurar los permisos para ambas plataformas:

Android

Agrega a android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

iOS

Agrega a ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Necesitamos acceso a tu cámara para capturar fotos de tu documento de identidad y validar tu identidad.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Necesitamos acceso al micrófono para el video de verificación.</string>

Uso Rápido

Método 1: MetaGVerification (Recomendado)

La forma más sencilla de integrar el SDK con gestión automática de resultados:

import 'package:flutter/material.dart';
import 'package:metag_flutter_sdk/metag_flutter_sdk.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Verificación MetaG')),
        body: Center(
          child: ElevatedButton(
            onPressed: () {
              MetaGVerification.show(
                context: context,
                idConnection: 'tu_id_de_conexion',
                apiKey: 'tu_api_key',
                identificador: 'identificador_unico_usuario',
                env: 'QA_IT_01', // o 'production'
                onCompleteWithResult: (bool success, String message) {
                  if (success) {
                    // ✅ Verificación exitosa - token biométrico generado
                    print('Éxito: $message');
                    ScaffoldMessenger.of(context).showSnackBar(
                      SnackBar(
                        content: Text(message),
                        backgroundColor: Colors.green,
                      ),
                    );
                    // Navegar a la siguiente pantalla
                    Navigator.pushNamed(context, '/dashboard');
                  } else {
                    // ❌ Error en la verificación
                    print('Error: $message');
                    ScaffoldMessenger.of(context).showSnackBar(
                      SnackBar(
                        content: Text(message),
                        backgroundColor: Colors.red,
                      ),
                    );
                  }
                },
                onComplete: () {
                  print('Overlay de verificación cerrado');
                },
              );
            },
            child: Text('Iniciar Verificación'),
          ),
        ),
      ),
    );
  }
}

Método 2: IdentityVerificationFlow

Para un control más directo del flujo de navegación:

import 'package:flutter/material.dart';
import 'package:metag_flutter_sdk/metag_flutter_sdk.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: IdentityVerificationFlow(
        idConnection: 'tu_id_de_conexion',
        apiKey: 'tu_api_key',
        identificador: 'identificador_unico_usuario',
        env: 'QA_IT_01',
        extra: {
          'custom_field': 'valor_personalizado',
        },
        onComplete: () {
          print('Verificación completada exitosamente');
          // Realizar acciones post-verificación
        },
      ),
    );
  }
}

Componentes del SDK

MetaGVerification

Componente principal que muestra el flujo de verificación como un overlay.

Propiedades:

context (BuildContext) - Contexto de Flutter requerido
idConnection (String) - ID de conexión de MetaG
apiKey (String) - API key para autenticación
identificador (String) - Identificador único del usuario
env (String) - Ambiente ("QA_IT_01", "production", etc.)
extra (Map<String, dynamic>?) - Datos adicionales opcionales
onCompleteWithResult (Function(bool, String)?) - Callback con resultado y mensaje
onComplete (VoidCallback?) - Callback simple al completar

IdentityVerificationFlow

Widget principal del flujo de verificación de identidad.

Propiedades:

idConnection (String) - ID de conexión de MetaG
apiKey (String) - API key para autenticación
identificador (String) - Identificador único del usuario
env (String) - Ambiente de la API
extra (Map<String, dynamic>?) - Configuración adicional
onComplete (VoidCallback?) - Callback al completar el flujo

Páginas del Flujo

El SDK incluye las siguientes páginas en el flujo de verificación:

WelcomePage - Pantalla de bienvenida e instrucciones
IdFrontPage - Captura del frente del documento
IdBackPage - Captura del reverso del documento
VideoSelfiePage - Grabación de video selfie
BiometricPhotoPage - Captura de foto biométrica
SuccessPage - Confirmación de verificación exitosa

Servicios Disponibles

El SDK expone los siguientes servicios para uso avanzado:

InitProcessService - Inicializa el proceso de verificación
SetupService - Configuración del ambiente
ValidateDpiService - Validación de documento de identidad
ValidateVideoService - Validación de video selfie
ValidateBiometricService - Validación de foto biométrica
ConnectionService - Gestión de conexiones con la API

Modelos de Datos

Config

Configuración del SDK con credenciales y ambiente.

InitProcessResponse

Respuesta de inicialización del proceso de verificación.

ValidationResponse

Respuesta genérica de validación con estado y mensajes.

BiometricToken

Token generado tras verificación biométrica exitosa.

Para más detalles sobre el uso de tokens biométricos y gestión de resultados, consulta BIOMETRIC_TOKEN_USAGE.md.

Ejemplo Completo

Consulta el directorio example/ para una aplicación de ejemplo completa.

Para ejecutar el ejemplo:

cd example
flutter pub get
flutter run

Flujo de Verificación

El proceso de verificación sigue estos pasos:

Inicialización - Se establece conexión con la API de MetaG
Bienvenida - Pantalla con instrucciones para el usuario
Documento Frontal - Captura de la parte frontal del documento de identidad
Documento Reverso - Captura de la parte trasera del documento
Video Selfie - Grabación de video del rostro del usuario
Foto Biométrica - Captura de foto facial para validación biométrica
Validación - Procesamiento y validación de todos los datos capturados
Resultado - Generación del token biométrico o mensaje de error

Manejo de Errores

El SDK maneja automáticamente errores comunes:

Errores de red: Reintentos automáticos con timeout
Errores de cámara: Mensajes claros para permisos denegados
Errores de validación: Feedback específico al usuario
Errores de API: Gestión de respuestas de error del servidor

Ejemplo de manejo de errores:

MetaGVerification.show(
  context: context,
  idConnection: 'id',
  apiKey: 'key',
  identificador: 'user123',
  env: 'QA_IT_01',
  onCompleteWithResult: (bool success, String message) {
    if (success) {
      // Caso exitoso
      print('Token biométrico generado: $message');
    } else {
      // Manejo de diferentes tipos de error
      if (message.contains('network')) {
        // Error de red
        showRetryDialog(context);
      } else if (message.contains('validation')) {
        // Error de validación
        showValidationError(context, message);
      } else {
        // Error genérico
        showErrorDialog(context, message);
      }
    }
  },
);

Personalización

Configuración Adicional

Puedes pasar datos adicionales mediante el parámetro extra:

IdentityVerificationFlow(
  idConnection: 'id',
  apiKey: 'key',
  identificador: 'user123',
  env: 'QA_IT_01',
  extra: {
    'userId': '12345',
    'sessionId': 'abc-def-ghi',
    'customField': 'valor',
  },
  onComplete: () {
    // ...
  },
)

Ambientes Disponibles

QA_IT_01 - Ambiente de pruebas
production - Ambiente de producción
Otros ambientes personalizados según configuración

Requisitos del Sistema

Flutter SDK: >=3.9.2
Dart SDK: >=3.9.2
Android: API 21+ (Android 5.0+)
iOS: iOS 11.0+

Dependencias

http: ^1.2.0 - Comunicación con la API
camera: ^0.11.0+2 - Captura de imágenes y video

Documentación Adicional

📘 Uso de BiometricToken - Guía detallada sobre tokens y resultados
📝 CHANGELOG - Historial de cambios y versiones
📄 LICENSE - Términos de licencia

Solución de Problemas

Error: Permisos de cámara denegados

Asegúrate de que los permisos estén correctamente configurados en los archivos de configuración de Android/iOS.

Error: No se puede conectar con la API

Verifica que:

El apiKey sea correcto
El idConnection sea válido
El ambiente (env) esté bien configurado
Haya conexión a internet

La cámara no se muestra

Verifica los permisos en el dispositivo
Reinicia la aplicación
Verifica que la dependencia camera esté correctamente instalada

Contribuir

¡Las contribuciones son bienvenidas! Por favor:

Haz fork del repositorio
Crea una rama para tu feature (git checkout -b feature/amazing-feature)
Commit tus cambios (git commit -m 'Add amazing feature')
Push a la rama (git push origin feature/amazing-feature)
Abre un Pull Request

Soporte

Para problemas, preguntas o solicitudes de características:

Crea un issue en GitHub
Contacta al equipo de MetaG
Consulta la documentación oficial de MetaG

Licencia

Consulta el archivo LICENSE para más detalles.

Autores

Desarrollado por el equipo de MetaG

Versión: 0.0.1
Última actualización: Enero 2026