Mejores prácticas
Esta página consolida las pautas más importantes para integrar y mantener los SDKs de Unico. Seguir estas prácticas reduce los errores de integración, previene incidentes de seguridad y garantiza un lanzamiento fluido en producción.
Getting started
Unico ofrece una aplicación de referencia para cada SDK en el repositorio reference-apps. Cada aplicación implementa la jornada completa del usuario.
Los SDKs evolucionan continuamente para ofrecer mayor seguridad y nuevas funcionalidades. Aplicar actualizaciones con prontitud — especialmente las críticas — es esencial. Consulta la Política de actualización para conocer los plazos y las obligaciones.
Consulta la versión actual de cada plataforma a través de las notas de versión correspondientes:
- Notas de versión de Android
- Notas de versión de iOS
- Notas de versión de Flutter
- Web — Notas de versi ón del SDK de Jornadas
Update strategy
Es probable que tu aplicación cargue múltiples bibliotecas junto con el SDK de Unico. Actualizar varias dependencias a la vez dificulta identificar la causa raíz de los fallos. Actualiza el SDK de forma aislada y valídalo en un entorno de staging antes de combinarlo con otros cambios.
Al abrir un ticket de soporte por problemas de actualización, incluye:
- Lenguaje del SDK y tipo de implementación (nativo o híbrido)
- Framework utilizado
- Versión actual y versión objetivo
- API Key
- Descripción de los cambios y pasos para reproducirlos
- Resultados, errores, logs, capturas de pantalla o videos
JWT security
El JWT devuelto tras una captura exitosa está cifrado. No lo abras, analices ni serialices. Su estructura interna puede cambiar sin previo aviso. Úsalo exclusivamente al enviar imágenes a las APIs de Unico.
Para vistas previas de imágenes, utiliza el atributo Base64 provisto junto con el JWT — nunca decodifiques el JWT en sí.
Por razones de seguridad, el JWT debe enviarse al backend de Unico dentro de los 10 minutos posteriores a la captura. Los paquetes enviados fuera de este plazo son invalidados.
El JWT debe enviarse solo una vez. Si ocurre un error durante el envío, se debe realizar una nueva captura biométrica — no reutilices el mismo JWT.
Testing guidelines
Ejecutar el SDK en máquinas virtuales o emuladores genera códigos de error de seguridad (73006, 73600, 73400). Realiza siempre las pruebas en dispositivos físicos para evitar identificar erróneamente los errores y retrabajos innecesarios.
El SDK Web detecta DevTools abierto como una posible señal de fraude e invalida el envío. Cierra DevTools antes de ejecutar pruebas de captura de extremo a extremo.
Realiza pruebas en el entorno de staging de Unico
Antes de pasar a producción, ejecuta pruebas exhaustivas en el entorno de staging de Unico con escenarios realistas. Usa API Keys y configuraciones específicas del staging — nunca uses credenciales de producción en las pruebas.
El entorno de staging (UAT) de IDCloud aplica los mismos criterios de seguridad que producción. Las directrices a continuación explican por qué y cómo probar sin interrupciones.
Antes — detectaba, pero no rechazaba Las condiciones fuera del patrón de un uso real se identificaban, pero no impedían la captura.
Ahora — detecta y rechaza Las mismas condiciones ahora generan el rechazo de la prueba de vida, con el mismo rigor que producción.
Fidelidad — similitud con producción Lo que pasa en staging debe funcionar de la misma forma en producción — evitando que una integración aprobada en pruebas falle de forma inesperada después del go-live.
Al probar en condiciones cercanas al uso real, las capas de seguridad no afectan tu desarrollo.
Las herramientas de desarrollo que no son las estándar del mercado activan validaciones de seguridad, y la transacción puede ser bloqueada.
| Escenario | Situación |
|---|---|
| Flujo completo de la integración — captura, envío, respuesta de la API y retorno | ✅ Puedes |
| Escenarios funcionales: UI/UX, rendimiento, errores de negocio | ✅ Puedes |
| Dispositivo en la configuración estándar de un usuario final | ✅ Puedes |
| Integración con backend, APIs y procesamiento de datos | ✅ Puedes |
| Dispositivo con root/jailbreak | ❌ No puedes |
| Modo debug / depuración USB activa | ❌ No puedes |
| Emuladores o virtualización | ❌ No puedes |
| Cámaras virtuales o herramientas de automatización de captura | ❌ No puedes |
| Herramientas que alteren la conexión | ❌ No puedes |
| MDM corporativo o monitoreo activo en el dispositivo | ❌ No puedes |
| Sandbox en contenedor o máquina virtual | ❌ No puedes |
Cualquiera de estas condiciones puede generar el rechazo de la prueba de vida.
Habla con el equipo de soporte para recibir orientación sobre la configuración de tu entorno. No hay excepción, habilitación puntual ni flexibilización temporal — Unico mantiene el staging equalizado con producción durante el tiempo que considere necesario.
Platform-specific guidelines
No intentes integrar los SDKs nativos de Android o iOS dentro de una aplicación Flutter. Los puentes nativos frecuentemente producen errores no mapeados. Utiliza siempre el plugin Flutter dedicado de Unico.
Al actualizar el SDK Web, elimina los archivos de recursos antiguos de tu carpeta public antes de insertar los nuevos. Los archivos con nombres idénticos no se sobrescribirán automáticamente y pueden causar conflictos de versión.
Los artefactos de compilación de versiones anteriores del SDK pueden causar errores de dependencia después de una actualización. Antes de compilar una nueva versión:
- Flutter: elimina
pubspec.locky ejecutaflutter pub get - iOS: ejecuta
pod cache clean --allypod install - Android: ejecuta
./gradlew clean
Excluye el código del SDK de Unico de tu configuración de ofuscación. Ofuscar el SDK comúnmente causa fallos en las compilaciones de release que no aparecen en las compilaciones de debug. Consulta la documentación específica de cada plataforma para conocer las reglas de exclusión requeridas.
UX and performance
Estructura el flujo del SDK en dos etapas diferenciadas:
- Preparar — inicializa el SDK mientras la página carga (antes de la interacción del usuario).
- Abrir — lanza la cámara solo cuando el usuario activa la acción explícitamente.
Preparar el SDK con anticipación reduce la latencia percibida y mejora significativamente la experiencia del usuario.
Production rollout
Antes de desplegar en producción, verifica:
- Las API Keys de producción y las configuraciones de entorno son correctas
- El plan de rollback está definido y probado
- El protocolo de recopilación de logs está en marcha
- Los procedimientos de tickets de soporte están documentados para la gestión de fallos
- Todas las validaciones pasaron en el entorno de staging