Cómo usar el versionado semántico con Capgo OTA Updates

Guía de Configuración de Capgo

Aquí te explicamos cómo configurar Capgo para gestionar actualizaciones OTA y control de versiones fácilmente.

Pasos de Configuración Inicial

Comienza instalando el plugin de actualización de Capgo:

npm install @capgo/capacitor-updater
npx cap sync

Asegúrate de que tu archivo capacitor.config.json use un formato de versión semántica:

{
  "appId": "com.example.app",
  "appName": "Mi App",
  "version": "1.0.0"
}

Para proyectos más antiguos, actualiza los detalles de versión en estas ubicaciones:

• package.json (busca el campo version)
• android/app/build.gradle (actualiza versionName)
• ios/App/App.xcodeproj/project.pbxproj (actualiza CURRENT_PROJECT_VERSION)

Una vez configurado, inicializa Capgo con tu clave API:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.initialize({
  apiKey: 'TU_CLAVE_API'
})

Tabla de Referencia Rápida:

Integración de Control de Versiones

Capgo funciona bien con plataformas CI/CD, haciendo que las actualizaciones automatizadas sean simples. Las plataformas soportadas incluyen:

• GitHub Actions
• GitLab CI
• Azure DevOps
• Jenkins
• CircleCI

Si estás trabajando en desarrollo local, puedes deshabilitar las actualizaciones automáticas añadiendo esto a tu configuración:

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": false
    }
  }
}

Esto asegura que Capgo no sobrescribirá tus cambios locales. Una vez que tu configuración esté lista, sube tu primera versión:

capgo upload

Finalmente, notifica al plugin nativo sobre la salud del paquete en el archivo principal de tu app:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

await CapacitorUpdater.notifyAppReady()

Esta configuración asegura que tu app esté lista para implementaciones OTA fluidas y gestión de versiones.

Usando Versionado Semántico con Capgo

Gestión de Números de Versión

Capgo usa Versionado Semántico (SemVer) para gestionar versiones de apps, formateado como MAJOR.MINOR.PATCH. Así es como funciona:

• Versión Mayor (X.0.0): Aumenta el número MAJOR para cambios que rompen la compatibilidad.
• Versión Menor (1.X.0): Aumenta el número MINOR para nuevas características que mantienen compatibilidad.
• Versión Parche (1.0.X): Aumenta el número PATCH para correcciones de errores que no afectan la compatibilidad.

Al seguir las reglas SemVer, puedes simplificar la gestión de versiones y asegurar actualizaciones más suaves a través de tus canales de implementación.

Directrices de Control de Versiones

Capgo te permite gestionar implementaciones efectivamente configurando canales distintos para diferentes etapas de tu flujo de trabajo.

• Gestión de Versiones Basada en Canales: Organiza tu proceso de implementación creando canales separados para pruebas y producción. Por ejemplo:

  • Usa un canal “beta” (ej., 1.2.0-beta) para probar nuevas características.
  • Mantén un canal “producción” (ej., 1.2.0) para lanzamientos estables.
  • Añade canales específicos de plataforma (ej., “ios-hotfix” con versión 1.2.1) cuando abordes problemas específicos de plataforma.

• Configuración de Política de Actualización: Controla cómo se aplican las actualizaciones usando las opciones de configuración de Capgo. Por ejemplo:

  {
    "plugins": {
      "CapacitorUpdater": {
        "autoUpdate": true,
        "updateInterval": 30,
        "disableAutoUpdateBreaking": true
      }
    }
  }

  Esta configuración asegura que los usuarios reciban actualizaciones de parches automáticamente, mientras que las actualizaciones menores y mayores requieren aprobación manual.

• Estrategia de Reversión de Versiones: Usa identificadores de pre-lanzamiento para mantener opciones claras de reversión. Este enfoque te permite revertir a una versión anterior si ocurren problemas, mientras mantienes el versionado consistente a través de todos los canales.

Estas mejores prácticas facilitan la gestión de actualizaciones, prueba de nuevas características y mantenimiento de la estabilidad en tu proceso de implementación.

Implementación de Actualizaciones OTA

Una vez que tu configuración de gestión de versiones esté lista, sigue estos pasos para implementar actualizaciones OTA efectivamente.

Preparación de Actualización

Comienza actualizando la versión en package.json y capacitor.config.json. Asegúrate de que la versión siga el formato SemVer (MAJOR.MINOR.PATCH):

• Corrección de Error: Aumenta el número PATCH (ej., 1.0.1 → 1.0.2)
• Nueva Característica: Aumenta el número MINOR (ej., 1.0.0 → 1.1.0)
• Cambio Incompatible: Aumenta el número MAJOR (ej., 1.0.0 → 2.0.0)

Prueba exhaustivamente tu compilación y confirma que la app se comunica con el servidor usando notifyAppReady.

Luego, decide tu estrategia de actualización. Puedes elegir entre:

• Auto-Actualización: Forzar automáticamente requisitos de versión mínima.
• Control Manual: Especificar requisitos exactos de versión para actualizaciones.
• Basado en Canales: Usar canales para pruebas e implementaciones graduales.

Comandos de Actualización de Capgo CLI

Usa el CLI de Capgo para implementar tu actualización fácilmente. Así es cómo:

# Construye y sube tu actualización
npm run build
capgo upload

# Opcional: especifica un canal
capgo upload --channel beta

Capgo asegura una implementación segura con encriptación de extremo a extremo y gestión segura de claves.

“@Capgo es una forma inteligente de hacer actualizaciones de código en caliente (y no por todo el dinero del mundo como con @AppFlow) 🙂”

Una vez implementada, puedes monitorear actualizaciones a través del panel de control de Capgo. Las actualizaciones típicamente llegan a los usuarios en minutos después de que abren la app. El proceso funciona así:

• La app busca actualizaciones.
• Descarga la actualización en segundo plano.
• Marca la nueva versión como activa cuando el usuario sale de la app.
• Aplica la actualización en el siguiente inicio.

Para implementaciones a nivel empresarial, podrías querer integrar automatización CI/CD.

“¡Practicamos desarrollo ágil y @Capgo es crítico para entregar continuamente a nuestros usuarios!”

Solución de Problemas y Consejos

Problemas de Gestión de Versiones

Gestionar el versionado semántico en Capgo puede a veces complicar las implementaciones de actualizaciones. Para evitar sobrescribir tu trabajo de desarrollo, configura lo siguiente en tu archivo capacitor.config.json:

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": false,
      "disableAutoUpdateBreaking": true
    }
  }
}

Si una actualización falla, esto es lo que puedes hacer:

• Establece autoUpdate en false durante el desarrollo.
• Desinstala la app.
• Reinstálala con la versión corregida.
• Reactiva las auto-actualizaciones una vez que todo esté estable.

Para actualizaciones de versión mayor, usa la bandera disableAutoUpdateBreaking y escucha el evento majorAvailable para manejar actualizaciones apropiadamente:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.addListener('majorAvailable', async () => {
  // Maneja la actualización mayor aquí
})

Combinando estas configuraciones con buenas prácticas de equipo, puedes mantener consistencia de versiones y reducir errores.

Control de Versiones en Equipo

Una vez que las actualizaciones individuales están gestionadas, es crucial para los equipos establecer prácticas sólidas de control de versiones.

“Probar cada cambio antes de fusionarlo con el repositorio principal reforzará la estabilidad y evitará errores costosos” [4]

Aquí hay algunos métodos para asegurar consistencia:

• Define una rama como el repositorio principal para actuar como fuente de verdad.
• Usa canales separados de Capgo para entornos de desarrollo y producción.
• Automatiza cargas de versiones vía pipelines CI/CD.
• Documenta todos los cambios de código con mensajes de commit claros y detallados.

Para equipos más grandes, la siguiente matriz de gestión de versiones puede ayudar a organizar actualizaciones:

Pasos de Recuperación de Actualizaciones

Incluso con precauciones, las actualizaciones pueden fallar. Si eso ocurre, sigue estos pasos de recuperación:

1. Volver a una versión estable anterior.
2. Incrementar los números de versión para las nuevas correcciones (nota: los números de versión no se pueden reutilizar después de la eliminación) [2].
3. Verificar las actualizaciones durante el inicio de la aplicación para asegurar que funcionan como se espera.

El actualizador de Capgo está diseñado para manejar interrupciones. Por ejemplo, si el servidor no está accesible o se elimina una actualización, la aplicación continúa funcionando normalmente [3]. Además, las solicitudes de red fallidas se reintentarán automáticamente durante el próximo inicio de la aplicación [3]. Esta resiliencia incorporada minimiza el tiempo de inactividad y asegura operaciones más fluidas.

Resumen

El Versionado Semántico, combinado con Capgo, ha hecho que las actualizaciones OTA para aplicaciones Capacitor sean más eficientes. Con 947.6 millones de actualizaciones entregadas y 1,400 aplicaciones en producción usando este sistema [1], los procesos de implementación se han vuelto 81% más eficientes [1]. Esta configuración permite a los desarrolladores enviar actualizaciones rápidamente y de manera controlada, evitando los retrasos de las tiendas de aplicaciones.

Esto es lo que dicen los desarrolladores:

“Implementamos actualizaciones OTA de Capgo en producción para nuestra base de usuarios de +5000. Estamos viendo una operación muy fluida, casi todos nuestros usuarios están actualizados en minutos después de que el OTA se implementa en @Capgo.” - colenso [1]

El sistema de versionado MAJOR.MINOR.PATCH facilita la comunicación de cambios importantes, nuevas características y correcciones de errores [5]. Esto es especialmente útil para equipos que gestionan varias versiones cada semana a través de la plataforma de Capgo.

La solución encriptada de Capgo, integrada con herramientas de CI/CD, también es económica - reduciendo costos hasta $26,100 en cinco años [1]. Sus canales personalizables aseguran que las actualizaciones lleguen a los usuarios correctos en el momento adecuado.

“¡Practicamos el desarrollo ágil y @Capgo es crítico para entregar continuamente a nuestros usuarios!” - Rodrigo Mantica [1]