Versión de destino

Esta guía explica cómo entregar automáticamente la última versión compatible del paquete a los usuarios en función de su versión nativa de la aplicación. de manera similar a la aproximación de Ionic AppFlow. Esto garantiza un manejo simplificado de actualizaciones y lanzamientos más rápidos, mientras se evitan problemas de compatibilidad.

Migrar desde Ionic AppFlow?

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

Resumen

El sistema de versión de Capgo te permite:

• Entregar actualizaciones compatibles automáticamente a usuarios según su versión nativa de la aplicación
• Prevenir cambios disruptivos evitar que lleguen a versiones de aplicación incompatibles
• Administrar múltiples versiones de aplicación de manera simultánea 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 AppFlowsabes cuán crítico es asegurarte de que los usuarios reciben solo actualizaciones compatibles. AppFlow automatizó la coincidencia de paquetes de actualizaciones en vivo con versiones nativas de la aplicación, evitando que se entregara JavaScript incompatible a versiones nativas antiguas de code.

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

• Mayor control sobre la coincidencia de versiones
• Strategias múltiples (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 disruptivos
• Quieres evitar que los paquetes más nuevos rompan las versiones nativas antiguas de code
• Estás migrando a los usuarios gradualmente de una versión a otra
• Estás migrando desde AppFlow y quiere mantener la misma seguridad de actualización

¿Cómo Funciona

Capgo utiliza un enfoque de múltiples capas 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 Canal: Ruta diferentes versiones de la aplicación a diferentes canales de actualización
3. Controles de Versión Semántica: Bloquea automáticamente las actualizaciones a través de fronteras de mayor/minor/patch
4. Anulaciones de Nivel de Dispositivo: Dirige actualizaciones específicas a dispositivos o grupos de usuarios

Flujo de coincidencia 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 local plugin channel}
    D -->|setChannel value| E[Use local setChannel channel]
    D -->|No local channel| F{Check defaultChannel in App}
    F -->|Has defaultChannel| G[Use App's defaultChannel]
    F -->|No defaultChannel| H[Use Cloud Default Channel]
    C --> I{Check Version Constraints}
    E --> I
    G --> I
    H --> I
    I -->|Compatible| J[Deliver Update]
    I -->|Incompatible| K[Skip Update]

Estrategia 1: Ruta de versión basada en canal

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 canal
• App v2.x (50,000 usuarios con cambios disruptivos) → 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: 'atBackground',
      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: 'atBackground',
      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: 'atBackground',
      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

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

Ventajas

• Cero code cambios - La ruta del canal sucede automáticamente
• - Separación clara - Cada versión tiene su propio pipeline de actualizaciones
• - Puede enviar actualizaciones a grupos de versiones específicas - Los despliegues son seguros
• - Los cambios disruptivos nunca llegan a versiones incompatibles targetLanguage

Estrategia 2: Controles de versión semántica

Utilice los controles de versión semántica integrados de Capgo para evitar actualizaciones a través de límites de versión. No habilitar actualizaciones automáticas entre versiones principales

Sección titulada “No habilitar actualizaciones automáticas entre versiones principales”

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

Los usuarios de la aplicación con versión

• recibirán actualizaciones hasta 1.2.3 will receive updates up to 1.9.9
• Los usuarios no No recibirán automáticamente 2.0.0 la versión
• evita que los cambios de versión rompan la aplicación en versiones antiguas de code
• La comparación utiliza la línea base nativa enviada como version_build

Opciones de control granular

# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (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

Estrategia 3: Restricciones de versión nativa Sección titulada “Estrategia 3: Restricciones de versión nativa” Indique una versión mínima de la aplicación nativa ( MAJOR.MINOR.PATCH ) en cada paquete para que __CAPGO_KEEP_0__ solo lo envíe a dispositivos cuya binaria nativa es lo suficientemente nueva.

Esta utiliza la estrategia de metadatos de canal (

Esta estrategia solo funciona si siguemin_update_version) on each bundle so Capgo only delivers it to devices whose native binary is new enough.

para las versiones de su aplicación. Asegúrese de que los números de versión de su aplicación sigan el formato. Esta estrategia utiliza la estrategia de metadatos de canal (--disable-auto-update metadata) más --min-update-version o --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Título de la sección: Habilitar la configuración de metadatos en el canal

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Título de la sección: Establecer una versión nativa mínima al subir

ventana de terminal

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

O dejamos que Capgo establezca el piso desde la compatibilidad del paquete nativo:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

Cómo Funciona

Cómo Funcionaversion_buildCon la estrategia de metadatos, los dispositivos cuya base nativa ( min_update_version ) es inferior a la del paquete se saltan la actualización. Solo los dispositivos en esa versión o superior la reciben. Consulte Compatibilidad --auto-min-update-version para

detalles.

1. Necesario nuevo plugin nativo

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Cambios nativos API que rompen la compatibilidad

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "3.0.0"

3. Migración gradual

   # one-time: enable metadata gating on beta
   npx @capgo/cli@latest channel set beta --disable-auto-update metadata
   
   # Test bundle only on latest native version
   npx @capgo/cli@latest bundle upload \
     --channel beta \
     --min-update-version "2.5.0"

Estrategia 4: Prevención de la degradación automática

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

Habilitar en Configuración de Canal

En el panel de control Capgo:

1. Vaya a Canal contexto: nombre de característica de canales de Capgo. Página/área: página de marketing de soluciones de Capgo. Rol: etiqueta de UI corta o elemento de navegación. Visto en: página soluciones/white-label.astro. Clave de mensaje `solutions_white_label_visual_cell2_value` (Valor de celda visual de soluciones de marca blanca).
2. → Seleccione su canal Habilitar
3. “Desactiva la descarga automática bajo nativo”

Or via CLI:

npx @capgo/cli@latest channel set production --no-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 hacia abajo)

Esto es útil cuando:

• Los usuarios instalaron manualmente una versión más nueva desde la tienda de aplicaciones
• Debes asegurarte de que los usuarios siempre tengan las últimas actualizaciones de seguridad
• Quieres prevenir errores de regresión

Estrategia 5: Targetización a nivel de dispositivo

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

Forzar 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 Capgo panel de control:

1. Ir a Dispositivos → Encontrar dispositivo
2. Hacer clic Establecer Canal o ¿Qué canal elegir?
3. Establecer Versión
4. Sobreescribir con una versión específica de canal o paquete

Actualizaciones de Prueba

Actualizaciones de Prueba

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

Sección titulada “Flujo de Trabajo Completo de AppFlow”

Aquí hay un ejemplo completo que combina todas las estrategias: 1. Configuración inicial (App v1.0.0)

# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
  --disable-auto-update metadata \
  --no-downgrade

capacitor.config.ts

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

2. Cambio de versión que rompe la compatibilidad (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
  --disable-auto-update metadata \
  --no-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: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Envía actualizaciones a ambas versiones

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

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

4. Monitorear la distribución de versiones

Utilice el Capgo panel de control para seguir:

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

5. Deprecar la 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 canal

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

1. Sobrescritura de dispositivo (Panel de control o API) - Mayor prioridad y visible en la interfaz de usuario de Sobrescritura de dispositivo
2. Canal de plugin local via setChannel() - Almacenado solo en el dispositivo y no se muestra en la interfaz de usuario de Sobrescritura de dispositivo
3. defaulChannel en capacitor.config.ts
4. Canal predeterminado (Configuración de Cloud) - Prioridad más baja

Ejemplo de Precedencia

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

La interfaz de usuario de Sobrescritura de Dispositivo solo muestra sobrescripciones establecidas desde la consola o Public API. Llamando setChannel() desde la aplicación valida el canal con el servidor, luego lo almacena localmente en el dispositivo.

Prácticas recomendadas

1. Siempre establezca 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

# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

# Test on beta channel first
npx @capgo/cli@latest bundle upload \
  --channel beta \
  --auto-min-update-version

# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

5. Monitorear la distribución de versiones

Revisa regularmente tu tablero:

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

Comparación con Ionic AppFlow

Para equipos que están migrando desde Ionic AppFlow¿Cómo compara Capgo con la versión de destino:

Característica	AppFlow de Ionic	Capgo
Versionamiento basado en versión	Ruteo basado en versión automático	Automático mediante defaultChannel (+ varias estrategias)
Versionamiento semántico	Apoyo básico	Avanzado con --disable-auto-update (mayor/minor/patch)
Restricciones de versión nativas	Configuración manual en la consola de AppFlow	Integrado --min-update-version / --auto-min-update-version con canales de metadatos
Gestión de canales	Web UI + CLI	Web UI + CLI + API
Interfaz de usuario web + __CAPGO_KEEP_0__ + __CAPGO_KEEP_1__	Superposiciones de dispositivo	Full control via Dashboard/API
Control total a través de Dashboard/__CAPGO_KEEP_0__	Prevención de descenso automático	Sí a través de --no-downgrade
Mantenimiento de varias versiones	Gestión de rama/canal manual	Automático con precedencia de canal
Autoalojamiento	No	Sí (control completo)
Análisis de versiones	Básico	Detalles de métricas por versión

Paridad de AppFlow y más allá

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

Resolución de problemas

Usuarios que no reciben 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 Configuración

   npx @capgo/cli channel list

4. Override de dispositivo: Verifique si el dispositivo tiene un override manual

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

Paquete entregado a la versión incorrecta

1. Revisar canal predeterminado: Asegúrese de que el canal esté correcto en capacitor.config.ts
2. Verificar carga de paquete: Verifique si el paquete se cargó en el canal deseado
3. Inspeccionar versión de actualización mínima: Confirme --min-update-version (o --auto-min-update-version) se estableció y el canal utiliza --disable-auto-update metadata

Cambios importantes que afectan versiones antiguas

1. Solución inmediata: Sobrescriba dispositivos afectados con paquete seguro
   • Panel de control → Dispositivos → Selección en masa → Establecer versión
2. Solución a largo plazo: Crear canales con versiones y mantener ramas separadas
3. Prevención: Siempre prueba las 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 de manera muy similar en Capgo, con mayor flexibilidad:

Mapa conceptual

Concepto de AppFlow	Capgo Equivalente	Notas
Canal de Implementación	Capgo Canal	El mismo concepto, pero más poderoso
Bloqueo de Versión Nativa	--min-update-version / --auto-min-update-version	Control más detallado
Prioridad del Canal	Precedencia del Canal (sobreescribir → en la nube → por defecto)	Precedencia más transparente
Objetivo de la Implementación	Control de canal + semver	Disponibles varias estrategias
Canal de producción	production nombre del canal (o cualquier otro)	Nombres flexibles
Despliegue basado en Git	subir paquete CLI desde rama	Misma secuencia de trabajo
Compatibilidad automática de versiones	defaultChannel Restricciones de versión +	Mejorado con varias estrategias

Diferencias clave para usuarios de AppFlow

1. Mayor control: Capgo te ofrece varias estrategias (canales, semver, versión nativa) que se pueden combinar
2. Mejor visibilidad: La consola muestra la distribución de versiones y problemas de compatibilidad
3. API de acceso: Control programático completo sobre la versión de destino
4. Auto-hospedaje: Opción para ejecutar tu propio servidor de actualizaciones con la misma lógica de versión

Pasos de migración

1. Mapa tus canales de AppFlow a Capgo canales (usualmente 1:1)
2. Establecer defaultChannel en capacitor.config.ts para cada versión mayor
3. Configurar reglas de semver si desea bloqueo automático en las fronteras de versión
4. Subir conjuntos de versiones específicas utilizando --min-update-version (el canal debe utilizar la estrategia de metadatos)
5. Monitorear la distribución de versiones en Capgo panel de control

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, consulte la Guía de Migración de AppFlow a Capgo.

Patrones Avanzados

Implementación 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 Funcionalidad 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 múltiples estrategias para la entrega de actualizaciones específicas de versión:

1. Ruteo basado en canales: Separación automática de versiones mediante defaultChannel
2. : Versión semántica: Evita actualizaciones a lo largo de fronteras de versión mayor/minor/patch
3. Restricciones de versión nativa: Requiere versión nativa mínima para paquetes
4. Prevención de descenso automático: Nunca envíe paquetes más antiguos a versiones nativas más nuevas
5. Device Overrides: Control manual para pruebas y targeting

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

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

• Guía de cambios importantes - Estrategia de versionamiento de canales detallada
• Gestión de canales - Referencia completa de configuración de canales
• Comportamiento de actualización - Retrasos y condiciones de versiones nativas

Siga adelante desde la configuración de versiones

Si estás utilizando Configuración de Versión para planificar la ruta de canal y el lanzamiento en etapas, conecta con Canal para los detalles de implementación en Canal, Canal para los detalles de implementación en Canal, Canal Solución de Pruebas Beta para el flujo de trabajo del producto en Solución de Pruebas Beta, y __CAPGO_KEEP_0__ Solución de Enfoque de Versión para el flujo de trabajo del producto en Solución de Enfoque de Versión.