Saltar al contenido principal

Mejores prácticas para la implementación de SDKs

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​

Usa una PoC para facilitar tu implementación

Unico ofrece Pruebas de Concepto (PoCs) con ejemplos de código funcional en todos los lenguajes compatibles. Demuestran las secuencias de métodos esperadas y los patrones de integración. Accede a las PoCs disponibles a través del sistema de tickets de soporte del portal de clientes.

Mantén siempre tus SDKs actualizados

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.

Identifica la última versión disponible

Consulta la versión actual de cada plataforma a través de las notas de versión correspondientes:

Update strategy​

Evita actualizar el SDK y otros componentes simultáneamente

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.

Obtención de ayuda con una actualización del SDK

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​

No manipules el objeto JWT
No abras ni modifiques el JWT cifrado

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í.

Envía el JWT dentro de los 10 minutos
advertencia

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.

Envía el JWT solo una vez
advertencia

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​

No uses virtualización ni emuladores

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.

No mantengas DevTools abierto durante capturas web

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.

Platform-specific guidelines​

Flutter: usa el plugin Flutter de Unico

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.

Web: elimina los archivos de recursos antiguos al actualizar versiones

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.

Mobile: limpia la caché antes de compilar nuevas versiones

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.lock y ejecuta flutter pub get
  • iOS: ejecuta pod cache clean --all y pod install
  • Android: ejecuta ./gradlew clean
Configuración de ofuscación

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​

Separa el flujo de preparación y apertura de la cámara en dos pasos

Estructura el flujo del SDK en dos etapas diferenciadas:

  1. Preparar — inicializa el SDK mientras la página carga (antes de la interacción del usuario).
  2. 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​

Crea una lista de verificación segura para el lanzamiento en producción

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
Última actualización el