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

metag_flutter_sdk 0.0.3 metag_flutter_sdk: ^0.0.3 copied to clipboard

Metadata