Versión objetivo

Esta guía explica cómo entregar automáticamente el paquete compatible más reciente a los usuarios en función de su versión nativa de la aplicación. de manera similar a la aproximación de Ionic AppFlowEsto garantiza un manejo simplificado de actualizaciones y un despliegue más rápido, 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 proporciona la misma capacidad con aún más control y flexibilidad. Consulta la Guía de Migración de AppFlow para obtener instrucciones de migración paso a paso.

Resumen

El sistema de objetivo de versión de Capgo te permite:

• Entrega automáticamente actualizaciones compatibles a los usuarios según su versión nativa de la aplicación
• Prevenga cambios que rompen la aplicación de llegar a versiones de la aplicación incompatibles
• Administre varias versiones de la aplicación simultáneamente sin lógica compleja
• Implemente actualizaciones de manera fluida a segmentos de usuarios específicos

¿Por qué la versión de destino importa (Sobre todo para usuarios de AppFlow)?

Si está familiarizado con Ionic AppFlowEntendes cómo es crucial asegurarte de que los usuarios solo reciben actualizaciones compatibles. AppFlow automatizó la coincidencia de paquetes de actualizaciones en vivo con versiones nativas de la aplicación, evitando que se entregue JavaScript incompatible a versiones nativas antiguas 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)
• Necesitas mantener la compatibilidad hacia atrás mientras implementas cambios rotos
• Quieres evitar que los paquetes más nuevos rompan versiones nativas antiguas code
• Estás migrando a los usuarios gradualmente de una versión a otra
• Estás migrando desde AppFlow y deseas 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 Versión Semántica: Bloquea automáticamente las actualizaciones a través de fronteras de mayor/minor/patch
4. Device-Level Overrides: Dirija a dispositivos específicos o grupos de usuarios

Flujo de coincidencia de versiones

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: Ruteo de versiones basado 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 canal
• App v2.x (50,000 usuarios con cambios disruptivos) → v2 canal
• App v3.x (10,000 usuarios beta) → v3 canal

Implementación

Sección titulada “Implementación”

// 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

Ruta Automática

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 JavaScript code!

Beneficios

• Sin cambios code - La ruta de canales sucede automáticamente
• Separación clara - Cada versión tiene su propio pipeline de actualizaciones
• Objetivos flexibles - Actualiza a grupos de versiones específicas
• Despliegues seguros - Cambios importantes nunca llegan a versiones incompatibles

Estrategia 2: Controles de versión semántica

Utilice Capgo’s integrados controles de versión semántica para evitar actualizaciones a través de límites de versión.

Deshabilitar Actualizaciones Automáticas a Versión Mayor

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

Esta configuración significa:

• Los usuarios en la versión de la aplicación 1.2.3 recibirá actualizaciones hasta 1.9.9
• Los usuarios NO recibirán la versión 2.0.0 de manera automática
• Evita que los cambios de ruptura lleguen a versiones nativas más antiguas code

Opciones de Control Granular

# 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 la versión semántica (semver) para las versiones de tu aplicación. Asegúrate de que los números de versión sigan el MAJOR.MINOR.PATCH formato.

Estrategia 3: Restricciones de versión nativa

Establece requisitos de versión nativa mínimos para los paquetes para evitar la entrega a dispositivos incompatibles.

Usando la condición de retraso de versión nativa

Al subir 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 la versión nativa 1.x NO recibirán este paquete. Solo los dispositivos en 2.0.0+ lo obtendrán. Esto es perfecto para actualizaciones que requieren nuevas APIs nativas o complementos.

Casos de Uso

1. Se requiere un nuevo complemento 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 que rompen

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

Estrategia 4: Prevención de Descargas Automáticas

Evitar 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. Ir a Canales → Seleccionar su canal
2. Habilitar “Deshabilitar la actualización automática bajo nativo”
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 hacia atrás)

Esto es útil cuando:

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

Estrategia 5: Detección por 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' })
  }
}

Opción de dispositivo de la consola

En el Capgo de la consola:

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

Pruebas de actualizaciones

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

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 with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-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 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: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Envíe 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. Monitore la 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 crash 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 existan múltiples configuraciones de canal, Capgo utiliza este orden de precedencia:

1. Sobrescritura de Dispositivo (Panel de control o API) - Mayor prioridad
2. Sobrescritura de Nube a través de setChannel() Llamar
3. Canal por defecto in capacitor.config.ts
4. Canal 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' canal.

Consejos de uso

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. Utilice 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

Ventana de terminal

# ✅ 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 Lanzamiento

# 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 nuevas?
• ¿Las versiones antiguas siguen recibiendo un alto tráfico?
• ¿Deberías deprecate los canales antiguos?

Comparación con Ionic AppFlow

For equipos que migran desde Ionic AppFlow, aquí está cómo la versión de Capgo se compara en términos de versión objetivo:

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
Semántica de versión	Apoyo 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 de usuario web + CLI	Interfaz de usuario web + CLI + API
Sobrescrituras de dispositivo	Control limitado a nivel de dispositivo	Control total a través de la consola/API
Prevención de descargas automáticas	Sí	Sí mediante --disable-downgrade
Mantenimiento de varias versiones	Gestión de rama/kanal manual	Automático con precedencia de canal
Autohospedaje	No	Sí (control completo)
Análisis de versiones	Básico	Detalles por versión

Paridad de AppFlow y Más

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

Solució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: Verificar si el paquete tiene requisitos de versión nativos

   • Panel de control → Paquetes → Verificar la columna de 'Versión nativa'

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

   npx @capgo/cli channel list

4. : Verificar si el dispositivo tiene un override manualPanel de control → Dispositivos → Buscar dispositivo → Verificar canal/versión

   • __CAPGO_KEEP_0__

Bundle Entregado a la Versión Incorrecta

1. Revisar defaultChannelAsegúrate de que el canal sea correcto en capacitor.config.ts
2. Verificar Carga de BundleVerifica que el bundle se haya cargado en el canal pretendido
3. Inspeccionar Versión NativaConfirma que --native-version la bandera se utilizó correctamente

Cambios Rotos que Afectan Versiones Antiguas

1. Solución Inmediata: Sobreescribir dispositivos afectados a paquete seguro
   • Panel de control → Dispositivos → Seleccionar 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á migrando desde Ionic AppFlow, la versión de destino funciona muy de manera similar en Capgo, con mayor flexibilidad:

Mapa de conceptos

AppFlow Concepto	Capgo Equivalente	Notas
Canal de Despliegue	Capgo Canal	El mismo concepto, más poderoso
Versión Nativa Bloqueada	--native-version Banderín	Control más detallado
Prioridad de Canal	Precedencia de Canal (sobreescritura → en la nube → por defecto)	Precedencia más transparente
Destino de despliegue	Control de canal + semver	Disponibles varias estrategias
Canal de producción	production Nombre del canal (o cualquier otro)	Nombres flexibles
Despliegue basado en Git	CLI carga de paquete desde rama	Mismo flujo de trabajo
Compatibilidad automática de versiones	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. Mejor visibilidad: La consola muestra la distribución de versiones y problemas de compatibilidad
3. API Acceso: Control total programático sobre la versión objetivo
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. Configura tus canales de AppFlow a Capgo canales (usualmente 1:1)
2. Configura defaultChannel en capacitor.config.ts para cada versión mayor
3. Configura reglas de semver si deseas bloqueo automático en las fronteras de versión
4. Carga conjuntos de versiones específicas usando --native-version flag
5. Monitorea la distribución de versiones In Capgo panel de control

Guía de Migración Completa

Para obtener instrucciones de migración completas, incluyendo el reemplazo de SDK y la asignación de API, consulte el 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 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 proporciona varias estrategias para la entrega de actualizaciones específicas de versión:

1. Ruta basada en canales: Separación automática de versiones mediante defaultChannel
2. Gestión de versiones semánticas: Evita actualizaciones entre fronteras de versión mayor/minor/patch
3. Restricciones de versión nativas: Requiere mínimo versión nativa para paquetes
4. Prevención de Descargas Automáticas: 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 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 - Detallada estrategia de versión de canal
• Gestión de Canales - Referencia completa de configuración de canal
• Comportamiento de Actualización - Retrasos y condiciones de la versión nativa

Sigue adelante desde la versión objetivo

Si estás utilizando Versionamiento de versión para planificar la ruta de canales y el despliegue en etapas, conecta con Canales para los detalles de implementación en Canales, Canales para los detalles de implementación en 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 Solución de Enfoque de Versión.