Alcance de versiones

Esta guía explica cómo entregar automáticamente la última versión compatible del paquete a los usuarios según su versión nativa de la aplicación. similar a Ionic AppFlow’s enfoqueEsto garantiza un manejo de actualizaciones simplificado y lanzamientos más rápidos, evitando problemas de compatibilidad.

Migrar desde Ionic AppFlow?

Si estás proveniente de Ionic AppFlow, esta guía es especialmente importante para ti. AppFlow automatizaba la correspondencia 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 Instrucciones paso a paso para la migración.

Resumen

El sistema de versión de Capgo te permite:

• Entregar actualizaciones compatibles de manera automática a los usuarios según su versión nativa de la aplicación
• Prevenir cambios que rompen la aplicación de llegar a versiones de aplicación incompatibles
• Gestionar múltiples versiones de la aplicación de manera simultánea sin lógica compleja
• Realizar actualizaciones suaves a segmentos de usuarios específicos

Por qué la versión de destino importa (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ó automáticamente los conjuntos de live update para versiones nativas de la aplicación, evitando que se entregara JavaScript incompatible a versiones nativas más antiguas de code.

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

• Control más detallado 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)
• Deben mantener la compatibilidad hacia atrás mientras se implementan cambios disruptivos
• Quieren evitar que los paquetes más nuevos rompan las versiones nativas antiguas code
• Están migrando a los usuarios gradualmente de una versión a otra
• Están migrando desde AppFlow y quieren 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: Prevenga 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. Control de versiones semánticasAutomáticamente bloquear actualizaciones entre versiones principales/minoristas/patch.
4. Sobrescrituras a nivel de dispositivo: Target specific devices or user groups

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 aproximación recomendada 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: Configura 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: Crea canales

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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: Sube 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 aplicación instalado. ¡No se requieren cambios en el código code!

Beneficios

• Cero cambios code - El ruteo de canales ocurre automáticamente
• Separación clara Cada versión tiene su propio pipeline de actualizaciones
• Configuración flexible - Actualizar a grupos de versiones específicas
• Implementación segura - Cambios importantes nunca llegan a versiones incompatibles

Estrategia 2: Controles de versión semántica

Utilice Capgo’s integrado Control de versiones semánticas Desactivar Actualizaciones Automáticas entre Versiones Principales

Disable Auto-Update Across Major Versions

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

Esta configuración significa:

• Los usuarios de la aplicación con versión 1.2.3 recibirán actualizaciones hasta 1.9.9
• Usuarios podrán NO recibirán la versión 2.0.0 automáticamente
• Evita que los cambios de ruptura lleguen a versiones nativas antiguas code
• La comparación utiliza la 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

Esta estrategia solo funciona si sigues la semántica de versionado (semver) para las versiones de tu aplicación. Asegúrate de que tus números de versión sigan el MAJOR.MINOR.PATCH formato.

Estrategia 3: Restricciones de Versión Nativa

Specifica una versión mínima de la aplicación nativa (min_update_version ) en cada paquete para que Capgo solo lo envíe a dispositivos cuya binaria nativa es lo suficientemente nueva.

Esta utiliza el canal metadatos estrategia (--disable-auto-update metadata) más --min-update-version o --auto-min-update-version estrategia de canal más metadatos --native-version bandera de CLI.

Habilite la configuración de metadatos para 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

Establecer una versión nativa mínima en la carga

Al subir un paquete, pase la versión nativa más baja que pueda recibir:

# 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 deje 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

Con la estrategia de metadatos, los dispositivos cuyos niveles base nativos ("version_build) está debajo de la versión del paquete. min_update_version skip la actualización. Solo los dispositivos en esa versión o superior la reciben. Consulte Compatibilidad para --auto-min-update-version detalles.

Casos de uso

1. Nueva Placa Nativa Requerida

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

2. Actualizaciones Nativas de API

   # 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 Descenso Automático

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

Habilitar en Configuración de Canal

En el Capgo panel de control:

1. Ir a Canales Seleccionar su canal
2. Habilitar Deshabilitar la desescalada automática en nativo
3. Guardar cambios

O mediante 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 desactualización)

Esto es útil cuando:

• Users manually installed a newer version from the app store
• Debes asegurarte de que los usuarios siempre tengan las últimas actualizaciones de seguridad
• Quieres evitar bugs de regresión

Estrategia 5: Targeteo 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 de dispositivo

En el Capgo panel de control:

1. Vaya a Dispositivos → Encuentra dispositivo
2. Haga clic Establecer Canal o Establecer Versión
3. Ovérvela con una versión específica de canal o paquete
4. El dispositivo recibirá actualizaciones de la fuente sobrescrita

Pruebas de Actualizaciones

Use device overrides to test updates on your own device before rolling out to all users.

Flujo de trabajo completo estilo 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. Lanzamiento de cambio disruptivo (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. Monitorea la distribución de versiones

Utiliza 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 congelamientos 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 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 UI de Sobrescritura de dispositivo
2. Canal de plugin local a través de setChannel() - Stored on the device only and not shown in the Device Override UI
3. defaultChannel en capacitor.config.ts
4. Canales por defecto (Configuración de Cloud) - Prioridad más baja

Ejemplo de precedencia

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

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

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. Prueba 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 migran desde Ionic AppFlowAquí está cómo compara Capgo la versión de destino.

Característica	Ionic AppFlow	Capgo
Ruteo basado en versión	Automático según la versión nativa	Automático mediante defaultChannel + múltiples estrategias
Versión semántica	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	Interfaz de usuario web + CLI	Interfaz de usuario web + CLI + API
Superposiciones de dispositivo	Control de dispositivo limitado	Control completo a través de la consola/API
Prevención de descargas automáticas	Sí	Sí a través de --no-downgrade
Mantenimiento de varias versiones	Gestión de rama/canal manual	Gestión de canal con precedencia automática
Autohospedaje	No	Sí (control completo)
Análisis de versiones	Basic	Detalles por versión

Paridad de AppFlow y más allá

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

Solución de problemas

Título de sección: Solución de problemas

Verifique lo siguiente:

1. Asignación de CanalVerificar que el dispositivo está en el canal correcto

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

2. Restricciones de Versión: Verificar si el paquete tiene requisitos de versión nativos

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

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

   npx @capgo/cli channel list

4. Sobrescritura de DispositivoVerificar si el dispositivo tiene override manual

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

Bundle entregado a la versión incorrecta

1. Revisar defaultChannel: Asegurarse de que el canal correcto en capacitor.config.ts
2. Verificar carga de Bundle: Verificar si el bundle se subió al canal previsto
3. Inspeccionar minima versión de actualización: Confirmar --min-update-version (o --auto-min-update-version) se estableció y el canal utiliza --disable-auto-update metadata

Cambios de ruptura que afectan versiones antiguas

1. Solución inmediata: Sobreescribir dispositivos afectados con paquete seguro
   • Dashboard → Devices → Bulk select → Set Version
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 Aplicación de flujo de IonicLa versión targeting funciona muy de manera similar en Capgo, con mayor flexibilidad.

Mapeo de conceptos

Concepto de flujo de Aplicación	Capgo Equivalente	Notas
Canal de despliegue	Capgo Canal	El mismo concepto, pero más poderoso
Bloqueo de versión nativa	--min-update-version / --auto-min-update-version	Más control granular
Prioridad de Canal	Precedencia de Canal (sobreescribir → en la 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 de versión automática	defaultChannel + restricciones de versión	Mejorado con varias estrategias

Diferencias clave para usuarios de AppFlow

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

Migración Pasos

1. Mapa tus canales de AppFlow a Capgo canales (usualmente 1:1)
2. Establecer defaultChannel in capacitor.config.ts para cada versión mayor
3. para cada versión mayor Si deseas bloqueo automático en límites de versión
4. Subir paquetes específicos de versión using --min-update-version (el canal debe utilizar la estrategia de metadatos)
5. Monitorear la distribución de versiones en el panel de Capgo

Guía de Migración Completa

Instrucciones de migración completas, incluyendo la sustitución de SDK y la mapeación de API, consulte 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 a través de 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. Ruteo basado en canal: Separación automática de versiones mediante defaultChannel
2. Numeralización semántica: Evita actualizaciones entre versiones principales/secundarias/puntuales
3. Restricciones de Versión Nativa: Requiere versión nativa mínima para paquetes
4. Prevención de Descenso Automático: Nunca entrega paquetes más antiguos a versiones nativas más nuevas
5. Oversights de Dispositivo: Control manual para pruebas y targeting

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

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

• Guía de Cambios Significativos - Estrategia detallada de versionado de canales
• Gestión de Canales - Referencia completa de configuración de canal
• Comportamiento de Actualización - Retrasos y condiciones de versión nativa

Sigue adelante desde la configuración de versión

Si estás utilizando Versión Dirigida to plan channel routing and staged rollout, connect it with Canales para el detalle de implementación en los Canales, Canales para el detalle de implementación en los canales, Canales para los detalles de implementación en Canales, Solución de Pruebas Beta para el flujo de trabajo del producto en Solución de Pruebas Beta, y Solución de Enfoque de Versión para el flujo de trabajo del producto en la Solución de Versionamiento.