Cambios importantes

Esta documentación explica cómo gestionar cambios incompatibles en tu app usando canales versionados. Este enfoque te permite mantener diferentes versiones de tu app asegurando que los usuarios reciban actualizaciones compatibles.

Escenario de ejemplo

Digamos que tienes:

• Versión de app 1.2.3 (versión antigua) - usa el canal production
• Versión de app 2.0.0 (nueva versión con cambios incompatibles) - usa el canal v2
• Live update 1.2.4 (compatible con 1.2.3)
• Live update 2.0.1 (compatible con 2.0.0)

Estrategia: usa siempre defaultChannel para las versiones principales

Enfoque recomendado: Configura un defaultChannel para cada versión principal. Esto garantiza que siempre puedas enviar actualizaciones a grupos de usuarios específicos sin depender de la asignación dinámica de canales.

// Version 1.x releases
defaultChannel: 'v1'

// Version 2.x releases
defaultChannel: 'v2'

// Version 3.x releases (future)
defaultChannel: 'v3'

Consejo

Ventajas de este enfoque:

• Ten siempre el control sobre qué usuarios reciben actualizaciones
• Sin cambio dinámico de canales necesario en tu app code
• Separación clara entre las distintas versiones de la app
• Flexibilidad to push updates to any specific version group

1. Crear canal para la nueva versión

# Create channel for version 2.x
npx @capgo/cli channel add v2

2. Actualizar la config de Capacitor para la versión 2.0.0

Actualiza tu configuración de Capacitor antes de compilar la versión 2.0.0 para la app store:

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      // ... other options
      defaultChannel: 'v2' // All 2.0.0 users will use v2 channel
    }
  }
};

export default config;

Nota

Para la versión 1.x: Si no configuraste un defaultChannel inicialmente, los usuarios de la versión 1.x están en el production canal. Para futuras versiones principales, configura siempre un canal específico como v3, v4, etc.

3. Gestionar ramas separadas de Code

Crea ramas de Git separadas para mantener la compatibilidad entre versiones de la app:

# Create and maintain a branch for version 1.x updates
git checkout -b v1-maintenance
git push origin v1-maintenance

# Your main branch continues with version 2.x development
git checkout main

Crítico: Nunca subas bundles de JavaScript a apps antiguas que esperen code/APIs nativas que no tengan. Genera siempre las actualizaciones desde la rama correspondiente:

• rama v1-maintenance: Para actualizaciones de apps 1.x (canal de producción)
• rama main: Para actualizaciones de apps 2.x (canal v2)

4. Subir bundles a sus respectivos canales

# For 1.x updates: Build from v1-maintenance branch
git checkout v1-maintenance
# Make your 1.x compatible changes here
npx @capgo/cli bundle upload --channel production

# For 2.x updates: Build from main branch
git checkout main
# Make your 2.x changes here
npx @capgo/cli bundle upload --channel v2

5. Habilitar la autoasignación

# Allow apps to self-assign to v2 channel
npx @capgo/cli channel set v2 --self-assign

6. Desplegar en la App Store

Compila y despliega la versión 2.0.0 en la app store. Todos los usuarios que descarguen esta versión (ya sean nuevos o existentes que actualicen) usarán automáticamente el canal v2, ya que está configurado en el bundle de la app.

Nota

¡No se necesitan cambios en code! Desde defaultChannel: 'v2' se incluye en la versión de la app store, todos los usuarios que descarguen la versión 2.0.0 usarán automáticamente el canal correcto.

Escalado a futuras versiones

Cuando publiques la versión 3.0.0 con más cambios incompatibles:

# Create channel for version 3.x
npx @capgo/cli channel add v3

// capacitor.config.ts for version 3.0.0
const config: CapacitorConfig = {
  // ...
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'v3' // Version 3.x users
    }
  }
};

Ahora puedes enviar actualizaciones a cualquier versión:

• production canal → Usuarios de la versión 1.x
• v2 canal → Usuarios de la versión 2.x
• v3 canal → Usuarios de la versión 3.x

7. Limpieza (tras la migración)

Una vez que todos los usuarios hayan migrado a la versión 2.x (aprox. 3-4 meses):

1. Eliminar defaultChannel de tu configuración de Capacitor
2. Elimina el canal v2:

npx @capgo/cli channel delete v2

3. Elimina la rama v1-maintenance:

git branch -d v1-maintenance
git push origin --delete v1-maintenance

Consejo

Este enfoque garantiza que los usuarios solo reciban actualizaciones compatibles con su versión de la app

Prueba siempre a fondo las actualizaciones en cada canal antes de desplegarlas

Nota

Puedes eliminar con seguridad el canal v2 en Capgo incluso si algunos usuarios aún tienen la sobrescritura de canal. Recibirán automáticamente las actualizaciones del canal de producción en su lugar.

Mantener las actualizaciones de la versión 1.x

Para enviar actualizaciones compatibles con la versión 1.x:

1. Cambia a la rama v1-maintenance:

git checkout v1-maintenance

2. Realiza tus cambios y haz commit:

# Make 1.x compatible changes
git add .
git commit -m "Fix for v1.x"
git push origin v1-maintenance

3. Compila y sube al canal de producción:

npx @capgo/cli bundle upload --channel production

Consejo

Mantén tu rama v1-maintenance actualizada con correcciones de errores compatibles con la versión 1.x, pero nunca integres cambios que rompan la compatibilidad desde main

Continuar a partir de Breaking Changes

Si estás usando Cambios importantes para planificar el enrutamiento de canales y el despliegue gradual, conéctalo con Canales para los detalles de implementación en Channels, Canales para los detalles de implementación en Channels, Canales para los detalles de implementación en Channels, Solución de beta testing para el workflow del producto en la solución de beta testing, y Solución de segmentación por versión para el workflow del producto en la solución de segmentación por versión.