Segmentación por versión

Esta guía explica cómo entregar automáticamente el último bundle compatible según la versión de la app nativa, de forma similar al enfoque de Ionic AppFlow. Esto simplifica la gestión de actualizaciones y acelera los rollouts, evitando problemas de compatibilidad.

¿Migras desde Ionic AppFlow?

Si vienes de Ionic AppFlow, esta guía es especialmente importante para ti. AppFlow emparejaba automáticamente las actualizaciones con las 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 instrucciones de migración paso a paso.

Resumen

El sistema de targeting por versiones de Capgo te permite:

• Entregar actualizaciones compatibles automáticamente a los usuarios según su versión nativa de la app
• Evitar breaking changes para que no lleguen a versiones incompatibles
• Gestionar varias versiones de la app a la vez sin lógica compleja
• Despliega actualizaciones sin fricciones a segmentos de usuarios específicos

Por qué importa el Version Targeting (especialmente para usuarios de AppFlow)

Si ya estás familiarizado con Ionic AppFlow, sabes lo importante que es garantizar que los usuarios reciban solo actualizaciones compatibles. AppFlow asociaba automáticamente los bundles live update con las versiones nativas de la app, evitando que se entregara JavaScript incompatible a code nativos más antiguos.

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

• Control más granular sobre el matching de versiones
• Múltiples estrategias (canales, semver, restricciones nativas)
• Mejor visibilidad de la distribución de versiones
• API y CLI se controlan junto con la gestión del dashboard

Este enfoque es especialmente útil cuando:

• Tienes usuarios en diferentes versiones principales de tu app (ej. v1.x, v2.x, v3.x)
• Necesitas mantener la compatibilidad hacia atrás al implementar breaking changes
• Quieres evitar que bundles nuevos rompan versiones antiguas de code nativo
• Estás migrando usuarios gradualmente de una versión a otra
• Estás migrando desde AppFlow y quieres mantener la misma seguridad en las Live Update

Cómo funciona

Capgo usa un enfoque multicapa para emparejar usuarios con updates compatibles:

1. Restricciones de Versión Nativa: Evita que se entreguen bundles a versiones nativas incompatibles
2. Enrutamiento basado en canales: Dirige distintas versiones de la app a diferentes canales de actualización
3. Controles de Semantic Versioning: Bloquea automáticamente actualizaciones entre cambios major/minor/patch
4. Overrides a nivel de dispositivo: Apunta 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 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: Enrutamiento de versiones por canal

Este es el enfoque recomendado para gestionar breaking changes 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 breaking changes) → v2 canal
• App v3.x (10.000 usuarios beta) → v3 canal

Implementación

Paso 1: Configurar canales para cada versión principal

// 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 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 bundles específicos por 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

Enrutamiento automático

Cuando los usuarios abren la app, se conectan automáticamente al canal asignado según el defaultChannel en su bundle instalado. ¡Sin cambios en el code de JavaScript!

Beneficios

• Cero cambios en code - El enrutamiento de canales es automático
• Separación clara - Cada versión tiene su propio pipeline de updates
• Targeting flexible - Envía updates a grupos de versiones específicos
• Rollouts seguros - Los breaking changes nunca llegan a versiones incompatibles

Estrategia 2: Controles de Semantic Versioning

Usa los controles de Capgo control de versionado semántico para evitar updates entre límites de versión.

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:

• Usuarios con la versión de la app 1.2.3 recibirán actualizaciones hasta la 1.9.9
• Los usuarios NO recibirán la versión 2.0.0 automáticamente
• Evita que los breaking changes lleguen a code nativos más antiguos
• La comparación utiliza el baseline nativo enviado 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

Requiere Semantic Versioning

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

Estrategia 3: Restricciones de versión nativa

Especifica una versión mínima de la app nativa (min_update_version) en cada bundle para que Capgo solo lo entregue a dispositivos con un binario nativo compatible.

Esto utiliza la estrategia de metadatos canal (--disable-auto-update metadata) más --min-update-version o --auto-min-update-version al hacer upload. No existe un --native-version flag de CLI.

Habilita el targeting por 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

Define una versión nativa mínima al hacer upload

Al subir un bundle, indica la versión nativa más baja que puede recibirlo:

# 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 deja que Capgo establezca el mínimo según 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 cuyo baseline nativo (version_build) es inferior al del bundle min_update_version omitirán la actualización. Solo los dispositivos en esa versión o superior la recibirán. Ver Compatibilidad para --auto-min-update-version detalles.

Casos de uso

1. Se requiere un 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 incompatibles en API nativo

   # 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 auto-downgrade

Evita que los usuarios reciban bundles más antiguos que su versión nativa actual.

Actívalo en Configuración del canal

En el dashboard de Capgo:

1. Ve a Canales → Selecciona tu canal
2. Activar “Desactivar el downgrade automático en Native Build”
3. Guardar cambios

O mediante CLI:

npx @capgo/cli@latest channel set production --no-downgrade

Ejemplo

• Dispositivo del usuario: Versión Native 1.2.5
• Bundle del canal: Versión 1.2.3
• Resultado: La actualización está bloqueada (sería un downgrade)

Esto es útil cuando:

• Los usuarios instalaron manualmente una versión más reciente desde la app store
• Necesitas asegurar que los usuarios siempre tengan los últimos parches de seguridad
• Quieres prevenir bugs de regresión

Estrategia 5: Targeting a nivel de dispositivo

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

Forzar una versión específica para testing

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' })
  }
}

Override de dispositivo desde el Dashboard

En el dashboard de Capgo:

1. Ve a Dispositivos → Buscar dispositivo
2. Haz clic Configurar Channel o Configurar Version
3. Sobrescribir con un channel o versión de bundle específica
4. El dispositivo recibirá actualizaciones de la fuente seleccionada

Prueba tus Updates

Usa overrides en el dispositivo para probar updates en tu propio equipo antes de lanzarlos a todos los usuarios.

Workflow completo estilo AppFlow

Aquí tienes 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. Lanzar un breaking change (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. Enviar 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. Monitorizar la distribución de versiones

Usa el dashboard de Capgo para trackear:

• ¿Cuántos usuarios hay en v1 vs v2?
• Tasas de adopción de bundles por versión
• Errores o crashes por versión

5. Deprecar versión antigua

Cuando el uso de v1 baje 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 varias configuraciones de canales, Capgo usa este orden de precedencia:

1. Override de dispositivo (Dashboard o API) - Prioridad máxima y visible en la UI de Device Override
2. Canal de plugin local mediante setChannel() - Solo se almacena en el dispositivo y no se muestra en la UI de Device Override
3. defaultChannel en capacitor.config.ts
4. Canal por defecto (Configuración en la nube) - Prioridad mínima

Ejemplo de precedencia

Si la app de un usuario tiene defaultChannel: 'v2' pero haces un override de su dispositivo a 'beta' en el dashboard, recibirán actualizaciones del 'beta' canal.

La interfaz de Device Override solo muestra los overrides configurados desde el dashboard o API público. Al llamar setChannel() desde la app, se valida el canal con el backend y luego se guarda localmente en el dispositivo.

Buenas prácticas

1. Configura siempre defaultChannel para versiones mayores

// ✅ 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. Usa Semantic Versioning

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Mantén 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 del despliegue

# 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. Monitorea la distribución de versiones

Revisa tu dashboard regularmente:

• ¿Los usuarios están actualizando a nuevas versiones nativas?
• ¿Las versiones antiguas siguen teniendo mucho tráfico?
• ¿Deberías dejar de usar canales antiguos?

Comparativa con Ionic AppFlow

Para equipos que migran de Ionic AppFlowasí es como se compara el version targeting de Capgo:

Característica	Ionic AppFlow	Capgo
Enrutamiento basado en versiones	Automático según versión nativa	Automático mediante defaultChannel + múltiples estrategias
Versionado semántico	Soporte básico	Avanzado con --disable-auto-update (mayor/menor/parche)
Restricciones de versión nativa	Configuración manual en AppFlow dashboard	Integrado --min-update-version / --auto-min-update-version con canales de metadatos
Gestión de canales	Interfaz web + CLI	Interfaz web + CLI + API
Overrides de dispositivos	Control limitado por dispositivo	Control total vía Dashboard/API
Prevención de downgrade automático	Sí	Sí, mediante --no-downgrade
Mantenimiento multiversión	Gestión manual de branch/channel	Automatizado con prioridad de channel
Self-hosting	No	Sí (control total)
Analytics de versiones	Básico	Métricas detalladas por versión

Paridad con AppFlow y más

Capgo ofrece todas las capacidades de targeting por versión que ofrecía AppFlow, además de mecanismos de control adicionales. Si dependías del version matching automático de AppFlow, verás que Capgo es igual de seguro y más flexible.

Solución de problemas

Los usuarios no reciben actualizaciones

Comprueba lo siguiente:

1. Asignación de canales: Verifica que el dispositivo esté en el canal correcto

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

2. Restricciones de versión: Comprueba si el bundle tiene requisitos de versión nativa

   • Dashboard → Bundles → Revisa la columna “Native Version”

3. Configuración de Semver: Verifica la disable-auto-update setting

   npx @capgo/cli channel list

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

   • Dashboard → Devices → Buscar dispositivo → Revisar channel/version

Bundle entregado a la versión incorrecta

1. Revisar defaultChannel: Asegurar que el channel sea el correcto capacitor.config.ts
2. Revisar Bundle Upload: Verificar que el bundle se subió al channel deseado
3. Inspeccionar min update version: Confirmar --min-update-version (o --auto-min-update-version) se configuró y el canal usa --disable-auto-update metadata

Breaking changes que afectan versiones antiguas

1. Solución inmediata: Forzar a los dispositivos afectados a un bundle seguro
   • Dashboard → Dispositivos → Selección múltiple → Establecer versión
2. Solución a largo plazo: Crear canales por versión y mantener ramas separadas
3. Prevención: Probar siempre las actualizaciones en dispositivos reales antes del rollout

Migración desde Ionic AppFlow

Si estás migrando desde Ionic AppFlow, el version targeting funciona de forma muy similar en Capgo, con mayor flexibilidad:

Mapeo de conceptos

Concepto de AppFlow	Equivalente en Capgo	Notas
Canal de despliegue	Canal de Capgo	Mismo concepto, más potente
Bloqueo de versión Native	--min-update-version / --auto-min-update-version	Control más granular
Prioridad de canales	Precedencia (override → cloud → default)	Precedencia más transparente
Target de despliegue	Control por canal + semver	Múltiples estrategias disponibles
Canal de producción	production channel (o cualquier nombre)	Nomenclatura flexible
Despliegue basado en Git	Subida de CLI desde una rama	Mismo flujo de trabajo
Coincidencia de versiones automática	defaultChannel + restricciones de versión	Mejorado con múltiples estrategias

Diferencias clave para usuarios de AppFlow

1. Más controlCapgo te ofrece múltiples estrategias (channels, semver, native version) que se pueden combinar
2. Mejor visibilidadEl dashboard muestra la distribución de versiones y problemas de compatibilidad
3. Acceso a API: Control programático total sobre el targeting de versiones
4. Autoalojamiento: Opción de ejecutar tu propio servidor de actualizaciones con la misma lógica de versiones

Pasos para la migración

1. Mapea tus canales de AppFlow a canales de Capgo (normalmente 1:1)
2. Configurar defaultChannel en capacitor.config.ts para cada versión mayor
3. Configura reglas semver si quieres bloqueo automático en límites de versión
4. Sube bundles específicos por versión usando --min-update-version (el canal debe usar estrategia de metadata)
5. Monitorea la distribución de versiones en el dashboard de Capgo

Guía de migración completa

Para instrucciones de migración completas, incluyendo el reemplazo de SDK y el mapeo de API, consulta la Guía de migración de AppFlow a Capgo.

Patrones avanzados

Rollout 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' })
  }
}

Feature flags 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()
  }
}

A/B testing 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 entregar actualizaciones por versión:

1. Enrutamiento por canales: Separación automática de versiones mediante defaultChannel
2. Versionado semántico: Evita actualizaciones entre cambios major/minor/patch
3. Restricciones de versión nativa: Requiere una versión nativa mínima para los bundles
4. Prevención de auto-downgrade: Nunca entrega bundles antiguos a versiones nativas nuevas
5. Overrides de dispositivo: Control manual para testing y targeting

Al combinar estas estrategias, obtendrás una entrega de actualizaciones automática tipo AppFlow con mayor flexibilidad y control. Elige el enfoque que mejor se adapte al versionado y workflow de despliegue de tu app.

Para más detalles sobre funciones específicas:

• Guía de Breaking Changes - Estrategia detallada de versionado de canales
• Gestión de canales - Referencia completa de configuración de canales
• Comportamiento de actualización - Retrasos y condiciones de la versión nativa

Continuar desde Version Targeting

Si estás usando Segmentación por versión 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.