SDK de Flutter: Añade Verificación de Identidad a tu App (ES)

Una integración del SDK de Flutter para la verificación de identidad debe mantener las credenciales permanentes y la autorización final en su backend, mientras que la aplicación móvil lanza un flujo de captura nativo con un token de sesión de corta duración. El SDK de Flutter de Didit expone una API de Dart sobre los SDK de verificación nativos de iOS y Android, devolviendo resultados tipados de finalización, cancelación o falla a la aplicación. La decisión completa sigue perteneciendo al webhook o al flujo de recuperación del backend.

Esta guía utiliza solo métodos y tipos de resultados de Dart verificados contra el código fuente y las pruebas locales actuales del SDK. Los detalles de las dependencias nativas cambian entre versiones, por lo que la configuración de la plataforma se describe por responsabilidad y se enlaza a la guía canónica del SDK en lugar de copiar un Podfile o un bloque de Gradle sensible a la versión.

Puntos clave

• Cree sesiones de producción en el backend. Mantenga la clave API fuera del dispositivo y envíe solo el token de sesión necesario para el SDK.
• Utilice el resultado tipado de Dart para la experiencia del usuario, no para la autorización. VerificationCompleted significa que el flujo del SDK finalizó; inspeccione el estado para la visualización y espere la decisión autorizada del backend.
• Maneje la cancelación, las fallas tipadas y los errores inesperados de la plataforma por separado. Necesitan diferentes recuperaciones y análisis.
• Trate la configuración nativa como infraestructura de lanzamiento. Las claves de privacidad de iOS, las autorizaciones de comunicación de campo cercano (NFC), los objetivos de implementación, las dependencias de Android, el empaquetado y los permisos deben probarse en dispositivos reales.
• Diseñe todo el ciclo de vida. La creación de sesiones, la entrega de la aplicación, la captura, la verificación del webhook, los cambios de estado idempotentes, la revisión, los reintentos y la observabilidad forman una sola integración.

Qué hace el SDK de Flutter de Didit

El paquete didit_sdk envuelve los SDK nativos de iOS y Android detrás de una interfaz Dart compartida. Lanza la interfaz de usuario de verificación como un flujo nativo de pantalla completa y regresa cuando el usuario completa, cancela o encuentra un error.

El SDK puede lanzar flujos de trabajo con Verificación de ID, Detección de Vida y otras comprobaciones configuradas. El flujo de trabajo determina qué pasos aparecen; la llamada de Flutter no los codifica.

La superficie pública de Dart relevante para el ciclo de vida es:

DiditSdk.startVerification(token, config: ...)
DiditSdk.startVerificationWithWorkflow(workflowId, vendorData: ..., config: ...)

Para producción, prefiera startVerification con un token creado en el backend. El método de ID de flujo de trabajo es más simple, pero da al backend menos control sobre los parámetros avanzados.

Arquitectura: backend, aplicación Flutter, SDK y webhook

El flujo de producción tiene cuatro límites de confianza:

Componente	Posee	No debe poseer
Su backend	Clave API, elección del flujo de trabajo, referencia del cliente, creación de sesión, estado final del cliente	Interfaz de cámara
Aplicación Flutter	Solicitud de entrega, UI de carga y recuperación, lanzamiento del SDK, análisis locales	Clave API permanente o autorización final
SDK de Flutter de Didit	Captura nativa y flujo de verificación configurado	Su decisión de derecho de producto
Trabajador de Webhook/recuperación	Ingestión de resultados autenticados, deduplicación, conciliación	Suposiciones de cliente no verificadas

La secuencia es:

1. La aplicación Flutter iniciada pide a su backend que inicie la verificación.
2. Su backend crea una sesión de verificación con el flujo de trabajo previsto y una referencia de cliente interna estable.
3. El backend devuelve el session_token con alcance a la aplicación.
4. La aplicación pasa ese token a DiditSdk.startVerification.
5. El SDK presenta el flujo nativo y devuelve un resultado tipado para una experiencia de usuario inmediata.
6. Su backend recibe y verifica el evento de resultado, concilia el estado canónico y actualiza el cliente según su política.
7. La aplicación lee el estado del cliente de su backend antes de otorgar acceso o reclamar la aprobación final.

Esta arquitectura no confía en una pantalla de éxito en el dispositivo.

Para el contrato del lado del servidor y el límite de eventos, consulte la guía de evaluación de la integración de la API de verificación de ID.

Instalar el paquete

Utilice el comando del paquete en lugar de copiar una versión que pueda quedar obsoleta:

flutter pub add didit_sdk

Luego importe la biblioteca pública:

import 'package:didit_sdk/sdk_flutter.dart';

Antes de actualizar, lea el registro de cambios y la documentación oficial del SDK de Flutter. Verifique los requisitos de plataforma declarados con su aplicación e imágenes de CI.

Siga las instrucciones de lanzamiento de Flutter para dependencias nativas; la mezcla de versiones arbitrarias puede crear incompatibilidad.

Configurar iOS y Android

Responsabilidades de iOS

La captura de identidad puede utilizar hardware y datos protegidos. Dependiendo del flujo de trabajo configurado y la variante del SDK, la configuración de iOS puede requerir:

• un objetivo de implementación apropiado;
• descripciones de uso de cámara y micrófono;
• descripción de uso de la biblioteca de fotos si se permiten cargas;
• descripción de uso de NFC y autorizaciones cuando la lectura de chips está habilitada;
• configuración compatible de CocoaPods;
• capacidades de firma y aprovisionamiento que coincidan con el uso de NFC;
• fuentes personalizadas registradas si se configura una fuente específica de la aplicación.

La falta de cadenas de propósito de privacidad puede terminar una aplicación de iOS. Pruebe el flujo de trabajo exacto en un dispositivo físico.

El soporte NFC puede elevar el objetivo de implementación mínimo o añadir dependencias nativas. Elija la variante del SDK que coincida con su flujo de trabajo y siga la documentación actual para su configuración de Podfile.

Responsabilidades de Android

En Android, verifique:

• requisitos mínimos de SDK y Java;
• repositorios y dependencias añadidas por el plugin;
• entradas de manifiesto de cámara, red y NFC;
• comportamiento de permiso de cámara en tiempo de ejecución;
• compatibilidad con Gradle y Kotlin;
• reglas de empaquetado para dependencias nativas o criptográficas;
• la variante del SDK all, core, autodetection o nfc;
• minificación de la compilación de lanzamiento y comportamiento de los recursos.

Su producto aún necesita contexto de permisos, recuperación de denegación, accesibilidad e instrucciones de soporte. Pruebe la denegación, interrupción, segundo plano, rotación y recreación de procesos.

Crear sesiones en el backend

Su backend debe llamar a la API de sesión utilizando una clave API del lado del servidor. Asocie cada sesión con:

• su identificador de cliente estable;
• el flujo de trabajo seleccionado;
• entorno;
• comportamiento de devolución de llamada o retorno cuando corresponda;
• configuración regional o detalles de contacto requeridos;
• detalles esperados del cliente donde la política los utilice;
• correlación interna y metadatos de política.

Nunca incruste la clave API de Didit en Dart, activos de la aplicación, configuración remota legible o una solicitud móvil.

Devuelva solo el token de sesión y el estado mínimo de lanzamiento. Manténgalo fuera de los análisis, informes de fallos, registros, uso del portapapeles y almacenamiento a largo plazo.

Hacer que las solicitudes de inicio sean idempotentes

Un cliente puede tocar dos veces, perder la conectividad después de que su backend cree una sesión, o reabrir la pantalla mientras un intento está activo. Utilice un identificador de solicitud estable y una lógica de backend que devuelva el intento apropiado existente en lugar de crear duplicados desconectados.

El botón de carga de su aplicación debe bloquear los toques repetidos obvios, pero la idempotencia del lado del servidor sigue siendo necesaria porque los clientes reintentan y los procesos se reinician.

Iniciar la verificación desde Dart

Este ejemplo completo de Dart utiliza solo la importación del SDK, el método, las clases de resultado, los campos de sesión, el enum de estado y los campos de error verificados en el código fuente del paquete:

import 'package:didit_sdk/sdk_flutter.dart';

Future<void> runIdentityVerification(String sessionToken) async {
  try {
    final result = await DiditSdk.startVerification(
      sessionToken,
      config: const DiditConfig(
        loggingEnabled: false,
      ),
    );

    switch (result) {
      case VerificationCompleted(:final session):
        switch (session.status) {
          case VerificationStatus.approved:
            print('Flow completed with approved client status.');
          case VerificationStatus.pending:
            print('Flow completed and still needs a backend decision.');
          case VerificationStatus.declined:
            print('Flow completed with declined client status.');
        }
        print('Session ID: ${session.sessionId}');
        return;
      case VerificationCancelled():
        print('The user cancelled the verification flow.');
        return;
      case VerificationFailed(:final error):
        print('SDK error: ${error.type.name}: ${error.message}');
        return;
    }
  } catch (error, stackTrace) {
    print('Unexpected platform error: $error');
    print(stackTrace);
  }
}

El ejemplo muestra la estructura del tipo. Una aplicación real debe actualizar el estado de la pantalla y actualizar el estado del backend, nunca desbloquear una cuenta solo desde esta función.

Por qué VerificationCompleted no siempre es aprobación

VerificationCompleted contiene SessionData, cuyo status es uno de:

• VerificationStatus.approved;
• VerificationStatus.pending;
• VerificationStatus.declined.

El flujo del SDK puede finalizar mientras la verificación permanece pendiente o rechazada. Una revisión humana o una verificación asíncrona también pueden cambiar el estado del backend después de que la llamada de la aplicación regrese. Nombre su estado de UI local “flujo completado” en lugar de “identidad aprobada” hasta que su backend confirme el resultado de la política.

No hay llamada de inicialización de Flutter

La superficie pública verificada de Flutter no expone ningún método de inicialización separado. No copie un patrón de inicialización nativo de Android en Dart. Si Android informa notInitialized a través del resultado de Flutter, trátelo como un problema de integración o de puente nativo e inspeccione la configuración del paquete.

Manejo de errores tipados y recuperación

Los tipos de error verificados del SDK son:

Tipo de error	Significado para la política de la aplicación	Recuperación segura
sessionExpired	El token ya no puede iniciar la sesión prevista	Solicitar al backend una sesión nueva y válida
networkError	El flujo nativo no pudo completar una operación de red	Preservar el contexto y ofrecer un reintento limitado
cameraAccessDenied	El acceso a la cámara requerido no está disponible	Explicar por qué es necesario y guiar la configuración o una ruta alternativa
notInitialized	La integración nativa de Android o el puente no están listos	Registrar el contexto de lanzamiento e investigar la configuración
apiError	El SDK o servicio devolvió una falla a nivel de API	Reintentar solo cuando sea seguro; conciliar el estado del backend
retryBlocked	El flujo impide otro intento automático	Detener el bucle y seguir la política de backend o soporte
unknown	El error nativo no se mapeó a un tipo Dart conocido	Preservar un respaldo seguro y datos de correlación

Las plataformas nativas pueden exponer diferentes detalles. Mantenga una ruta unknown.

Separar errores de resultados del cliente

Una falla de red no es un rechazo; la denegación de la cámara no es fraude; la cancelación no es una identidad fallida. Mantenga las categorías separadas en:

• mensajes de usuario;
• reglas de reintento;
• acceso al producto;
• herramientas de soporte;
• análisis;
• informes de fraude y conversión.

Reintentos limitados

Deje que el backend decida si una sesión existente puede continuar o si se requiere una nueva. Evite un bucle ilimitado que llama repetidamente al SDK con un token caducado o bloqueado. Rastree el número de intentos y la causa sin registrar el token o la evidencia de identidad.

Utilizar eventos del backend como fuente de verdad

El SDK devuelve un resultado de cliente compacto. La evidencia completa y el estado final llegan a través de la integración del lado del servidor. Su manejador de webhook debe:

1. recibir la solicitud sin procesar en la forma requerida por el esquema de firma documentado;
2. autenticar el evento y validar su frescura;
3. deduplicar su identificador de evento;
4. mapearlo a la sesión y al cliente esperados;
5. evitar que los eventos más antiguos sobrescriban el estado terminal posterior;
6. recuperar el estado canónico de la sesión cuando se requiera conciliación;
7. aplicar su política y persistir la razón;
8. devolver dentro del presupuesto de respuesta del proveedor;
9. procesar el trabajo lento posterior de forma asíncrona.

Asuma una entrega al menos una vez. Los eventos duplicados y fuera de orden son un comportamiento ordinario del sistema distribuido. Almacene el evento del proveedor y la transición interna por separado para que una auditoría pueda reconstruir ambos.

La aplicación debe sondear su backend solo para su propio estado de producto o usar su canal en tiempo real normal. No debe exponer una clave API del proveedor para recuperar el registro final directamente.

Construir un ciclo de vida de pantalla Flutter resiliente

Modelar estados locales explícitos

Una pantalla de verificación puede usar:

• inactivo;
• solicitando sesión;
• lanzando SDK;
• flujo del SDK abierto;
• conciliando decisión del backend;
• esperando revisión;
• aprobado;
• rechazado;
• error recuperable;
• cancelado.

Persista solo lo que sea seguro. Después de la muerte del proceso, pregunte al backend si ya existe una sesión activa o finalizada. No confíe en un booleano en memoria para decidir si crear otro intento.

Respetar el ciclo de vida del widget

Después de la llamada esperada, verifique mounted antes de setState, diálogos o navegación. Mantenga el estado del negocio fuera de la UI transitoria.

Manejar el segundo plano y la cancelación

Pruebe el cambio de aplicación, el bloqueo de pantalla, la navegación y la terminación de procesos. Defina el comportamiento de reanudación, reinicio y conciliación.

Diseñar la recuperación de permisos

Explique la necesidad de la cámara o NFC. Después de una denegación permanente, muestre una guía de configuración o una ruta alternativa accesible.

Configuración sin fuga de políticas

La superficie de DiditConfig de Flutter verificada sin conexión expone languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton y showLivenessCameraSwitchButton. Los campos de la cámara usan CameraLens.front o CameraLens.back; todas las opciones están tipadas en Dart y mapeadas a los SDK nativos.

Mantenga tres reglas:

1. habilite el registro detallado solo para desarrollo o una compilación de diagnóstico controlada;
2. no utilice la configuración de la UI como sustituto de la política del backend;
3. pruebe cada idioma compatible, fuente personalizada, comportamiento de cierre y política de cámara en ambas plataformas, incluido el comportamiento de respaldo cuando una lente o activo solicitado no esté disponible.

La composición del flujo de trabajo y la marca del producto pertenecen a la consola o al flujo de trabajo administrado por el backend en lugar de un laberinto de banderas de características móviles. Esto mantiene las vistas de iOS, Android, web y soporte alineadas.

Probar la integración

Pruebas de Dart y widgets

Envuelva el lanzamiento del SDK detrás de un servicio de aplicación para que las pruebas de pantalla puedan devolver:

• completado y aprobado;
• completado y pendiente;
• completado y rechazado;
• cancelado;
• cada falla tipada;
• una excepción de plataforma inesperada.

Afirme la limpieza del estado de carga, las comprobaciones de montaje, la visibilidad de reintentos, la actualización del backend y las categorías de análisis. No coloque tokens de sesión reales en los accesorios.

Pruebas de integración nativas

Ejecute compilaciones de depuración y lanzamiento en dispositivos físicos iOS y Android. Cubra:

• permisos por primera vez y previamente decididos;
• cámaras compatibles y no compatibles;
• variantes habilitadas para NFC y no NFC donde se utilicen;
• poca luz, desenfoque, deslumbramiento y orientación;
• conectividad lenta, perdida y restaurada;
• segundo plano y recreación de procesos;
• cancelación y lanzamiento repetido;
• caducidad de la sesión y bloqueo de reintentos;
• diferentes configuraciones regionales, escalado de fuentes, lectores de pantalla y movimiento reducido;
• firma de aplicaciones, minificación y resolución de dependencias de producción.

Un emulador es útil para pruebas de estado y errores, pero no puede representar todas las condiciones de cámara, NFC, biometría e integridad del dispositivo.

Pruebas de backend de extremo a extremo

Utilice casos de sandbox deterministas para cada estado de cliente documentado. Reproduzca eventos de prueba firmados, envíe duplicados fuera de orden, retrase la revisión y concilie después de un webhook simulado perdido. Confirme que la aplicación nunca otorga acceso antes de que cambie el estado de su backend.

Para el diseño de pruebas biométricas y los límites de ataque, consulte la guía de pruebas de vida.

Lista de verificación de seguridad y privacidad

Antes del lanzamiento, confirme que:

• las credenciales permanentes del proveedor existen solo en el backend;
• la aplicación recibe un token de sesión con alcance a través de un canal autenticado;
• los tokens y la evidencia están ausentes de los registros, análisis, URLs e informes de fallos;
• las solicitudes de creación del backend son idempotentes y están vinculadas a una referencia de cliente estable;
• la finalización del cliente nunca otorga directamente un derecho;
• las pruebas de firma de webhook, frescura, duplicación, orden y conciliación pasan;
• las descripciones de privacidad de iOS y los recorridos de permisos de Android utilizan texto de propósito claro;
• las capacidades y variantes de NFC coinciden con el flujo de trabajo y la firma de lanzamiento;
• el registro de depuración está deshabilitado para producción;
• la retención, el consentimiento, el aviso de privacidad, la eliminación y las rutas de soporte coinciden con su rol y la ley;
• la compatibilidad del SDK, las dependencias nativas, el SO y el dispositivo se monitorean después del lanzamiento;
• las decisiones de reversión y actualización forzada tienen propietarios.

Errores comunes de integración del SDK de Flutter

Envío de la clave API en Dart

Las aplicaciones móviles no pueden proteger una credencial de servidor permanente. Cree sesiones en su backend y pase un token con alcance.

Confiar en la devolución de llamada completada

El resultado del cliente es el estado de la interfaz de usuario. Confirme el estado autorizado y aplique la política en el backend.

Inventar métodos de otra plataforma

Flutter no expone todos los métodos nativos del SDK bajo el mismo nombre. Compile contra el paquete y verifique su código fuente público de Dart antes de escribir código de integración.

Copiar configuraciones nativas obsoletas

Las variantes del SDK, los objetivos de implementación y la configuración del administrador de paquetes cambian. Siga la documentación de la versión instalada y regístrela en su lista de verificación de lanzamiento móvil.

Tratar cada error como rechazo

El permiso, la red, la caducidad, la falla de la API, la cancelación y la decisión del cliente requieren diferentes recuperaciones y análisis.

Probar solo en un emulador

La cámara, NFC, permisos, firma y dependencias nativas requieren cobertura de dispositivos físicos y compilaciones de lanzamiento.

Uso de Didit en un flujo de trabajo de identidad de Flutter

El SDK de Flutter de Didit aparece como gratuito. Puede lanzar flujos de trabajo que contienen Verificación de ID, Detección de Vida y otras comprobaciones configuradas, mientras que los equipos gestionan rutas condicionales a través del Orquestador de Flujos de Trabajo.

Las tarifas de módulos publicadas están disponibles en la página de precios. El SDK maneja la experiencia de captura nativa; su backend sigue siendo responsable de la creación de sesiones, el manejo autenticado de resultados, el estado del cliente y las decisiones del producto.

Preguntas frecuentes

¿Qué método inicia la verificación?

Para una sesión de producción creada en el backend, llame a DiditSdk.startVerification(sessionToken). El SDK también expone DiditSdk.startVerificationWithWorkflow(...) para el modo de integración de ID de flujo de trabajo más simple.

¿Debe la aplicación Flutter contener la clave API de Didit?

No. Mantenga la clave API en el backend. La aplicación solo debe recibir el token de sesión con alcance requerido para su intento de verificación.

¿Significa VerificationCompleted aprobado?

No necesariamente. Su estado de sesión puede ser aprobado, pendiente o rechazado. Utilice el resultado para el estado de la interfaz inmediata y confirme la decisión autorizada a través de su backend.

¿Cómo se debe manejar la cancelación?

Trátelo como un resultado de usuario distinto. Preserve el estado de la sesión del backend, ofrezca una ruta clara de reanudación o reinicio según la política, y no etiquete la cancelación como fraude o rechazo.

¿El SDK de Flutter tiene un método de inicialización?

La API pública verificada de Dart no expone ningún método de inicialización separado. Siga las instrucciones de configuración nativa del paquete y utilice los métodos de inicio documentados.

¿Puede Flutter usar NFC para documentos de identidad?

El SDK nativo puede admitir NFC cuando la variante de paquete seleccionada, el dispositivo, la configuración de iOS o Android, las capacidades de firma y el flujo de trabajo lo permiten. Siga la documentación de la versión actual y pruebe en dispositivos físicos.

¿Qué debe hacer la aplicación mientras un caso está en revisión?

Muestre un estado pendiente veraz, permita que el cliente se vaya de forma segura y lea el estado final del producto de su backend cuando llegue el resultado autenticado.

Referencias primarias

• Documentación del SDK de Flutter de Didit
• Repositorio de código fuente del SDK de Flutter de Didit
• Documentación de la API de sesión de Didit
• Documentación de webhooks de Didit
• Documentación de Flutter: integración de plataforma
• Estándar de verificación de seguridad de aplicaciones móviles de OWASP

Una sólida integración del SDK de Flutter mantiene cada límite explícito: el backend crea el intento, la aplicación lanza un flujo nativo con alcance, los resultados tipados impulsan la recuperación, los eventos de servidor autenticados impulsan el estado del cliente, y las pruebas en dispositivos reales demuestran que los permisos, el ciclo de vida, las dependencias nativas y las rutas de falla funcionan fuera de la demostración del camino feliz.