Objetivos de versión

de manera similar al enfoque de Ionic AppFlow similar a la forma en que Ionic AppFlow lo hace. Esto garantiza un manejo de actualizaciones simplificado y una implementación más rápida, mientras se evitan problemas de compatibilidad.

¿Migrando desde Ionic AppFlow?

Si estás proveniente de Ionic AppFlow, esta guía es especialmente importante para ti. AppFlow automatizaba la coincidencia de actualizaciones con versiones nativas, y Capgo ofrece la misma capacidad con aún más control y flexibilidad. Consulta el Guía de migración de AppFlow para instrucciones de migración paso a paso.

Resumen

Capgo’s version targeting system allows you to:

• Evita cambios que rompan la aplicación Automáticamente entrega actualizaciones compatibles
• a los usuarios según su versión nativa de la aplicación evitar versiones de aplicaciones incompatibles
• Administrar múltiples versiones de aplicaciones simultáneamente sin lógica compleja
• Implementar actualizaciones de manera fluida a segmentos de usuarios específicos

¿Por qué la versión de destino es importante (sobre todo para usuarios de AppFlow)?

Si estás familiarizado con Ionic AppFlow, sabrás cuán crítico es asegurarse de que los usuarios reciban solo actualizaciones compatibles. AppFlow automatizó la coincidencia de paquetes de actualizaciones en vivo con versiones nativas de aplicaciones, evitando que se entregara JavaScript incompatibilidad a versiones nativas antiguas code.

Capgo ofrece las mismas garantías de seguridad, con características adicionales:

• Más control granular sobre la coincidencia de versiones
• Múltiples estrategias (canales, semver, restricciones nativas)
• Mejor visibilidad en la distribución de versiones
• API y CLI controlan junto con la gestión de la consola

Esta aproximación es particularmente útil cuando:

• Tienes usuarios en diferentes versiones principales de tu aplicación (por ejemplo, v1.x, v2.x, v3.x)
• Necesitas mantener la compatibilidad hacia atrás mientras se implementan cambios rotos
• Quieres evitar que los paquetes más nuevos rompan los code nativos más antiguos
• Estás migrando a los usuarios gradualmente de una versión a otra
• Estás migrando desde AppFlow y quieres mantener la misma seguridad de actualización

Cómo Funciona

Capgo utiliza un enfoque multiestratificado para emparejar a los usuarios con actualizaciones compatibles:

1. Restricciones de Versión Nativa: Evita que los paquetes se entreguen a versiones nativas incompatibles
2. Ruteo Basado en Canales: Ruta diferentes versiones de la aplicación a diferentes canales de actualización
3. Controles de Versionado Semántico: Bloquea automáticamente actualizaciones a lo largo de fronteras de versión mayor/minor/patch
4. Sobrescrituras a Nivel de Dispositivo: Dirige a dispositivos o grupos de usuarios específicos

Flujo de Emparejamiento de Versión

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

Estrategia 1: Ruta de versión basada en canales

Esta es la enfoque recomendado para gestionar cambios importantes y actualizaciones de versión mayor. Es similar al modelo de entrega de AppFlow.

Escenario de ejemplo

• App v1.x (100,000 usuarios) → production canales
• App v2.x (50,000 usuarios con cambios de ruptura) → v2 canal
• App v3.x (10,000 usuarios beta) → v3 canal

Implementación

Paso 1: Configurar canales para cada versión mayor

// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'production', // or omit for default
    }
  }
};

export default config;

// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v2', // Routes v2 users automatically
    }
  }
};

// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

Paso 2: Crear canales

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

Paso 3: Subir paquetes específicos de versión

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

Ruteo automático

Cuando los usuarios abren la aplicación, se conectan automáticamente a su canal designado según el defaultChannel en su paquete de instalación de la aplicación. ¡No se requieren cambios en el JavaScript code!

Ventajas

• Cero code cambios - La ruta de canal sucede automáticamente
• Separación clara - Cada versión tiene su propio pipeline de actualizaciones
• Diseño flexible - Se pueden enviar actualizaciones a grupos de versiones específicas
• Implementación segura - Los cambios disruptivos nunca llegan a versiones incompatibles

Estrategia 2: Controles de versionamiento semántico

Use Capgo’s built-in semantic versioning controls to prevent updates across version boundaries.

Deshabilitar actualizaciones automáticas entre versiones principales.

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

Esta configuración significa:

• Los usuarios con la versión de la aplicación 1.2.3 recibirán actualizaciones hasta 1.9.9
• Los usuarios no recibirán la versión automáticamente. 2.0.0 No se realizarán actualizaciones automáticas para versiones mayores.
• Evita que los cambios de ruptura lleguen a versiones nativas code

Opciones de control granulares

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch

# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Requerido Semántico de Versión

Esta estrategia solo funciona si sigues el semántico de versión (semver) para las versiones de tu aplicación. Asegúrate de que tus números de versión sigan el formato. MAJOR.MINOR.PATCH Estrategia 3: Restricciones de versión nativa

Sección titulada “Estrategia 3: Restricciones de versión nativa”

Formato

Usando nativeVersion Retraso Condición

Cuando subas un paquete, puedes especificar una versión nativa mínima:

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

Cómo Funciona

Los dispositivos en versión nativa 1.x NO recibirán este paquete. Solo los dispositivos en 2.0.0+ lo recibirán. Esto es perfecto para actualizaciones que requieren nuevas APIs nativas o plugins.

Uso de Casos

1. Necesario Nuevo Plugin Nativo

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. Cambios nativos de API

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. Migración gradual

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

Prevenir la degradación automática

Evitar que los usuarios reciben paquetes más antiguos que su versión nativa actual.

Habilitar en Configuración de canal

En la consola de Capgo:

1. Vaya a Canales → Seleccione su canal
2. Habilitar “Deshabilitar la actualización automática nativa”
3. Guardar cambios

O a través de CLI:

npx @capgo/cli channel set production --disable-downgrade

Ejemplo

• Dispositivo del usuario: Versión nativa 1.2.5
• Paquete de canal: Versión 1.2.3
• Resultado: La actualización está bloqueada (sería una actualización a una versión anterior)

Esto es útil cuando:

• Los usuarios instalaron manualmente una versión más reciente desde la tienda de aplicaciones
• Necesita asegurarse de que los usuarios siempre tengan las últimas actualizaciones de seguridad
• Quiere prevenir errores de regresión

Estrategia 5: Targetización a nivel de dispositivo

Sobreescribir la asignación de canal para dispositivos o grupos de usuarios específicos.

Forzar una versión específica para pruebas

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

Panel de control Opción de dispositivo

En el panel de control Capgo:

1. Ir a Dispositivos → Encontrar dispositivo
2. Hacer clic Establecer canal o Establecer versión
3. Sobreescribir con una versión específica de canal o paquete
4. El dispositivo recibirá actualizaciones desde la fuente sobrescrita

Pruebas de Actualizaciones

Utilice las sobrescripciones de dispositivo para probar actualizaciones en su propio dispositivo antes de implementarlas en todos los usuarios.

Completa Flujo de Trabajo AppFlow-Style

1. Configuración inicial (App v1.0.0)

Ventana de terminal

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'production',
    }
  }
};

2. Cambio de versión (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Empujar actualizaciones a ambas versiones

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. Monitorear distribución de versiones

Utilice el Capgo panel para seguir:

• ¿Cuántos usuarios están en v1 vs v2
• Tasas de adopción de paquetes por versión
• Errores o fallas por versión

5. Deprecar Versión Antigua

Una vez que el uso de v1 caiga por debajo del umbral:

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

Precedencia de canales

Cuando existen múltiples configuraciones de canales, Capgo utiliza este orden de precedencia:

1. Sobrescrito de dispositivo (Panel o API) - Mayor prioridad
2. Sobrescrito de Cloud a través de setChannel() llamada
3. canales predeterminados en capacitor.config.ts
4. Canales predeterminados (Configuración de Cloud) - Menor prioridad

Ejemplo de precedencia

Si la aplicación de un usuario tiene defaultChannel: 'v2' pero sobreescribiendo su dispositivo a 'beta' en la consola, recibirán actualizaciones del 'beta' canal.

Prácticas recomendadas

1. Establecer siempre defaultChannel para versiones principales

// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3

// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually

2. Utilizar la versión semántica

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Mantener ramas separadas

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. Probar antes de la implementación

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. Monitorear distribución de versiones

Revisa regularmente tu panel de control:

• ¿Los usuarios están actualizando a versiones nativas más recientes?
• ¿Las versiones antiguas siguen recibiendo un alto tráfico?
• ¿Deberías deprecar los canales antiguos?

Comparación con Ionic AppFlow

Para equipos que están migrando desde Ionic AppFlow, aquí está cómo la versión de Capgo se compara con respecto a la versión:

Característica	Ionic AppFlow	Capgo
Ruteo basado en versión	Basado automáticamente en la versión nativa	Basado automáticamente a través de defaultChannel + varias estrategias
Versión semántica	Soporte básico	Avanzado con --disable-auto-update (mayor/minor/patch)
Restricciones de versión nativa	Configuración manual en la consola de AppFlow	Integrado --native-version bandera en CLI
Gestión de canales	Interfaz web + CLI	Interfaz web + CLI + API
Sobreescribir dispositivos	Control limitado a nivel de dispositivo	Control total a través de la consola/API
Prevención de downgrade automático	Sí	Sí a través de --disable-downgrade
Mantenimiento de varias versiones	Gestión de rama y canal manual	Automatizado con prioridad de canal
Autohospedaje	No	Sí (control completo)
Análisis de versiones	Básico	Métricas detalladas por versión

Paridad con AppFlow y más allá

Capgo proporciona todas las capacidades de versión de destino que ofrecía AppFlow, más mecanismos de control adicional. Si se basó en la coincidencia automática de versiones de AppFlow, encontrará Capgo igualmente seguro con más flexibilidad.

Solución de problemas

Usuarios No Están Recebiendo Actualizaciones

Verifique lo siguiente:

1. Asignación de Canal: Verifique que el dispositivo está en el canal correcto

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. Restricciones de Versión: Verifique si el paquete tiene requisitos de versión nativa

   • Panel de control → Paquetes → Verifique la columna “Versión Nativa”

3. Configuración de Semver: Verifique la configuración del canal disable-auto-update __CAPGO_KEEP_0__

   npx @capgo/cli channel list

4. Override de dispositivo: Verificar si el dispositivo tiene override manual

   • Panel de control → Dispositivos → Buscar dispositivo → Verificar canal/versión

Paquete entregado a la versión incorrecta

1. Revisar defaultChannel: Asegurarse de que el canal sea correcto en capacitor.config.ts
2. Verificar carga de paquete: Verificar si el paquete se subió al canal deseado
3. Inspeccionar versión nativa: Confirm --native-version se utilizó correctamente

Cambios importantes que afectan versiones antiguas

1. Solución inmediata: Sobreescribir dispositivos afectados para paquete seguro
   • Panel de control → Dispositivos → Selección en bloque → Establecer Versión
2. Solución a largo plazo: Crear canales versionados y mantener ramas separadas
3. Prevención: Siempre probar actualizaciones en dispositivos representativos antes de la implementación

Migración desde Ionic AppFlow

Si estás migrando desde Ionic AppFlow, la versión objetivo funciona muy de manera similar en Capgo, con una mayor flexibilidad:

Mapeo de Conceptos

Concepto de AppFlow	Capgo Equivalente	Notas
Canales de Despliegue	Capgo Canal	Mismo concepto, más potente
Bloqueo de Versión Nativa	--native-version flag	Más control granular
Prioridad de Canal	Precedencia de Canal (sobreescribir → nube → predeterminado)	Precedencia más transparente
Destino de Despliegue	Canal + semver controla	Disponibles varias estrategias
Canal de Producción	production canal (o cualquier nombre)	Nombres flexibles
Despliegue basado en Git	CLI carga de paquete desde rama	Mismo flujo de trabajo
Compatibilidad automática	defaultChannel Restricciones de versión +	Mejorado con múltiples estrategias

Diferencias clave para usuarios de AppFlow

1. Más control: Capgo te da múltiples estrategias (canales, semver, versión nativa) que se pueden combinar
2. Visibilidad mejorada: La consola muestra la distribución de versiones y problemas de compatibilidad
3. API Acceso: Control completo programático sobre la versión objetivo
4. Autoalojamiento: Opción para ejecutar tu propio servidor de actualizaciones con la misma lógica de versión

Pasos de Migración

1. Asigna tus canales de AppFlow a los canales Capgo (usualmente 1:1)
2. Establece defaultChannel en capacitor.config.ts para cada versión mayor
3. Configura reglas de semver si deseas bloqueo automático en límites de versión
4. Subir conjuntos de versiones específicas utilizando --native-version flag
5. Monitorear distribución de versiones en la consola de Capgo

Guía de Migración Completa

Para obtener instrucciones de migración completas, incluyendo la sustitución de SDK y la asignación de API, consulta el Guía de Migración de AppFlow a Capgo.

Patrones Avanzados

Despliegue gradual por versión

// Gradually migrate v1 users to v2
async function migrateUsers() {
  const deviceId = await CapacitorUpdater.getDeviceId()
  const rolloutPercentage = 10 // Start with 10%

  // Hash device ID to get deterministic percentage
  const hash = hashCode(deviceId) % 100

  if (hash < rolloutPercentage) {
    // User is in rollout group - migrate to v2
    await CapacitorUpdater.setChannel({ channel: 'v2' })
  }
}

Banderas de características por versión

// Enable features based on native version
async function checkFeatureAvailability() {
  const info = await CapacitorUpdater.getDeviceId()
  const nativeVersion = info.nativeVersion

  if (compareVersions(nativeVersion, '2.0.0') >= 0) {
    // Enable features requiring v2.0.0+
    enableNewCameraFeature()
  }
}

Pruebas A/B entre versiones

// Run A/B tests within same native version
async function assignABTest() {
  const nativeVersion = await getNativeVersion()

  if (nativeVersion.startsWith('2.')) {
    // Only A/B test on v2 users
    const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
    await CapacitorUpdater.setChannel({ channel: variant })
  }
}

Resumen

Capgo ofrece varias estrategias para la entrega de actualizaciones específicas de versión:

1. Ruta basada en canales: Separación de versiones automática mediante defaultChannel
2. Versión semántica: Evita actualizaciones a través de fronteras de versión mayor/minor/patch
3. Restricciones de versión nativa: Requiere la versión mínima nativa para paquetes
4. Prevención de descenso automático: Nunca entrega paquetes más antiguos a versiones nativas más nuevas
5. Sobrescrituras de dispositivo: Control manual para pruebas y targeting

Al combinar estas estrategias, puedes lograr la entrega automática de actualizaciones con estilo de AppFlow, con aún más flexibilidad y control. Elige el enfoque que mejor se adapte al flujo de versión y despliegue de tu aplicación.

Para obtener más detalles sobre características específicas:

• Guía de cambios protegidos - Estrategia de versión de canales detallada
• Gestión de canales - Referencia completa de configuración de canales
• Comportamiento de actualización - Retrasos y condiciones de versión nativa