Navegando entre canales en Capgo: cómo cambiar de canal de actualización en runtime

¿Alguna vez has querido enviar un cambio directamente a un usuario específico para que lo revise y te dé feedback de inmediato, sin pedirle que descargue e instale un nuevo build desde TestFlight o Google Play?

He tenido clientes que me han pedido mejoras que podía implementar rápido, pero hacerles llegar los resultados para que las validaran implicaba lanzar una actualización a todos los usuarios (arriesgado para un cambio experimental) o crear un build único para ese cliente (un engorro para ambos).

Lo que faltaba era flexibilidad. Los desarrolladores querían poder servir diferentes actualizaciones a distintos grupos de usuarios, como stakeholders no técnicos, QA o toda la base de usuarios cuando fuera oportuno.

No había forma de que un build de producción cambiara a una versión en progreso, recopilara feedback y luego volviera a producción.

Es lo que cambiar de canal constantemente permite. Una app instalada en el dispositivo de un usuario puede cambiar de canal de actualización en tiempo de ejecución, convirtiendo una app de producción en un espacio flexible para revisión e iteración en lugar de un endpoint fijo. Esto es especialmente útil para stakeholders no técnicos que trabajan con apps de producción, permitiéndoles probar cambios y dar feedback directamente en la app que ya tienen instalada.

Entender los canales de actualización

Los canales de actualización son la forma en que Capgo dirige las actualizaciones a builds específicos. Cada build está asociado a un canal, y ese canal determina qué actualizaciones recibirá.

Por ejemplo, puedes publicar actualizaciones en un preview canal sin afectar a los usuarios en production. Antes, cambiar de canal requería instalar un Native Build distinto o cambiar manualmente las asignaciones de dispositivos desde el dashboard.

Los canales en Capgo te permiten:

Segmenta grupos de usuarios con distintas funciones
Realiza tests A/B asignando usuarios a distintos canales
Lanza nuevas funciones de forma gradual
Crea programas de beta testing
Depura problemas de producción con usuarios individuales

Si no estás familiarizado con los canales de actualización, la documentación de canales de Capgo los explica con más detalle.

¿Qué es el Channel Surfing?

El channel surfing permite que una app instalada obtenga actualizaciones de distintos streams sin reinstalarla. Una app puede cambiar de canales de actualización en runtime y seguirá recibiendo updates del nuevo canal seleccionado hasta que se desinstale o cambie de canal.

En la práctica, esto significa que un product owner o QA puede cambiar un production build a, por ejemplo, un preview channel para probar los últimos cambios. Al terminar el testing, vuelven a production sin necesidad de reinstalar o generar un preview build aparte.

Internamente, el channel surfing funciona permitiendo que la app le indique al cliente de updates qué canal usar. Esa elección se puede cambiar en runtime y permanece activa hasta que se limpie o se reemplace.

Cómo implementar Channel Surfing

Antes de probar el channel surfing, tu proyecto debe estar configurado con Capgo Live Updates. Para configurarlo, sigue estos pasos: guía de inicio rápido de Capgo.

El único setup requerido para el channel surfing es habilitar “Allow devices to self associate” en cada canal al que quieras cambiar desde el dashboard de Capgo. No se requieren cambios en code ni modificaciones de config adicionales.

En esencia, el cambio de canales se basa en una única llamada a API:

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

await CapacitorUpdater.setChannel({ channel: 'your-channel' });

Esto establece el canal que se usará al consultar Capgo en busca de actualizaciones. Más información sobre el SDK de setChannel API.

Cambio de canal instantáneo (v5.34.0+)

A partir de la versión del plugin 5.34.0, 6.34.0, 7.34.0 u 8.0.0 (según tu versión principal), setChannel() funciona de forma distinta y mucho más rápida:

Validación en el backend (solo lectura): Se envía una petición al backend de Capgo para validar que el canal esté permitido
Actualización del almacenamiento local: Si la validación es correcta, el canal se guarda en el local storage del dispositivo
Efecto instantáneo: La siguiente comprobación de actualizaciones usa el nuevo canal de inmediato

Anteriormente, setChannel() se guardaba el cambio de canal en la base de datos del backend (como los cambios en Dashboard o API). Los dispositivos debían esperar a la replicación del backend (hasta 2 minutos) para reconocer el nuevo canal. El nuevo comportamiento solo lee del backend (para validación) y lo almacena localmente, haciendo que el cambio de canal sea instantáneo.

Flujo completo de cambio de canal

Para una mejor experiencia de usuario, normalmente querrás hacer algo más que solo cambiar el canal y esperar al próximo reinicio de la app. Un enfoque común es buscar actualizaciones de inmediato, descargarlas si están disponibles y recargar la app para que el usuario llegue directamente a la actualización del canal seleccionado.

Un flujo típico es el siguiente:

Cambiar el canal (setChannel)
Buscar una actualización (getLatest)
Obtener y aplicar la actualización (download, set o next)
Recargar la app si es necesario (reload)

Aquí tienes un ejemplo completo:

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

async function switchChannel(selectedChannel: string) {
  try {
    // 1. Set the updates channel (with optional auto-update trigger)
    await CapacitorUpdater.setChannel({
      channel: selectedChannel,
      triggerAutoUpdate: true // Immediately check for updates
    });

    console.log(`Switched to channel: ${selectedChannel}`);

    // If you want more control, handle the update manually:
    // const latest = await CapacitorUpdater.getLatest();
    // if (latest.url) {
    //   const bundle = await CapacitorUpdater.download({
    //     url: latest.url,
    //     version: latest.version
    //   });
    //   await CapacitorUpdater.set({ id: bundle.id });
    // }

  } catch (error) {
    console.error('Failed to switch channel:', error);
  }
}

// Switch to the beta channel
switchChannel('beta');

Tú decides cómo estructurar este flujo. Puedes repartir estos pasos entre varias interacciones o ejecutarlos todos a la vez. Sea cual sea la estructura, asegúrate de contemplar los fallos. Los problemas de red o un canal inválido pueden impedir que se aplique una actualización.

El único requisito: habilitar el Self-Assignment

Esto es lo único que necesitas hacer para habilitar el cambio de canales. Antes de que tu app pueda cambiar a un canal usando setChannel(), debes habilitar el self-assignment para ese canal en el dashboard de Capgo:

Ve a la pestaña Canales sección en tu dashboard de Capgo
Haz clic en el nombre del canal que quieras gestionar
Activar “Permitir que los dispositivos se asocien solos”
Guardar cambios

Activa el self-assignment en los ajustes de canal

Eso es todo. No necesitas cambiar la config de tu app. No defaultChannel requiere ajustes adicionales. Solo activa el self-assignment en los canales a los que quieras que los usuarios puedan cambiar.

Si esta opción está desactivada, cualquier intento de llamar setChannel() con este canal fallará y el channelPrivate evento se disparará.

Listar canales disponibles

Puedes obtener la lista de canales disponibles para self-assignment:

const { channels } = await CapacitorUpdater.listChannels();

console.log('Available channels:', channels.map(c => c.name));
// Use this to build a channel selector UI

Esto solo devuelve los canales donde el self-assignment está habilitado.

Obtener el canal actual

Comprueba a qué canal está asignado el dispositivo actualmente:

const { channel } = await CapacitorUpdater.getChannel();

console.log('Current channel:', channel);

Volver al canal por defecto

Para eliminar el override del canal y volver al valor por defecto:

await CapacitorUpdater.unsetChannel({});

Esto desvincula el dispositivo de cualquier canal asignado específicamente, haciendo que use el defaultChannel en tu config o el valor por defecto de la nube.

Cómo probar el Channel Surfing

Para ver el channel surfing en acción, necesitarás un release build; el @capgo/capacitor-updater API está diseñado para release builds. En debug builds, la app suele cargar el JavaScript desde un servidor de desarrollo, saltándose el flujo normal de updates.

Requisitos

El único requisito para el channel surfing es habilitar “Permitir la autoasociación de dispositivos” en cada canal al que quieras permitir el cambio. No hace falta cambiar la config de tu app.

Crear un Test Build

Genera tu app como de costumbre:

bun run build && npx cap sync

Luego crea tus Native Build usando Xcode o Android Studio, o usa tu pipeline de CI/CD. La app arrancará en el canal que esté configurado por defecto en el dashboard de Capgo.

Publicar Updates en diferentes canales

Una vez instalada la app, publica updates en distintos canales:

# Publish to preview channel
npx @capgo/cli@latest bundle upload --channel preview

# Publish to production channel
npx @capgo/cli@latest bundle upload --channel production

Desde ahí, ve a tu UI de channel surfing en la app y activa el cambio de canal. La app debería descargar el update del canal seleccionado y recargarse con la nueva versión.

Crear una UI para el Channel Switcher

El channel surfing suele ser algo que quieres exponer a un grupo limitado de usuarios, no a todos. Por ejemplo, podrías tener un botón solo para empleados autenticados que cambie la app al canal de preview.

Aquí tienes un ejemplo de componente React para un channel switcher:

import { useState, useEffect } from 'react';
import { CapacitorUpdater } from '@capgo/capacitor-updater';

export function ChannelSwitcher() {
  const [currentChannel, setCurrentChannel] = useState<string>('');
  const [availableChannels, setAvailableChannels] = useState<string[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    loadChannelInfo();
  }, []);

  async function loadChannelInfo() {
    const { channel } = await CapacitorUpdater.getChannel();
    setCurrentChannel(channel || 'default');

    const { channels } = await CapacitorUpdater.listChannels();
    setAvailableChannels(channels.map(c => c.name));
  }

  async function handleChannelSwitch(channel: string) {
    setIsLoading(true);
    try {
      await CapacitorUpdater.setChannel({
        channel,
        triggerAutoUpdate: true
      });
      setCurrentChannel(channel);
      // App will update in background or on next restart
    } catch (error) {
      console.error('Failed to switch channel:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div>
      <p>Current channel: {currentChannel}</p>
      <div>
        {availableChannels.map(channel => (
          <button
            key={channel}
            onClick={() => handleChannelSwitch(channel)}
            disabled={isLoading || channel === currentChannel}
          >
            Switch to {channel}
          </button>
        ))}
      </div>
    </div>
  );
}

Problemas comunes con OTA Updates

Ninguno de estos es exclusivo del channel surfing, pero suelen hacerse evidentes al empezar a cambiar de canales en runtime.

Desajustes de versión en runtime

Los updates en Capgo están ligados a las versiones nativas de la app. Si la versión nativa de un update no coincide con la de la app instalada, el update no se descargará ni se aplicará. Al hacer channel surfing, esto suele verse como un cambio de canal sin que se aplique el update, aunque exista uno en ese canal.

Esto suele significar que el update se publicó desde una versión nativa distinta. Asegúrate de que el bundle de tu canal sea compatible con la versión nativa instalada en el dispositivo.

Eliminar o revertir actualizaciones

Si una app ya descargó una actualización de un canal, borrarla desde el dashboard de Capgo no la elimina de los dispositivos que ya la tienen. Borrarla solo detiene futuras descargas.

La forma más fiable de revertir una mala actualización es publicar una versión estable en el mismo canal. Esto crea una nueva actualización al principio del historial del canal, que los clientes tratarán como la última versión y aplicarán en su lugar.

Capgo también ofrece un mecanismo de rollback que puede instruir a los clientes para que vuelvan a aplicar una actualización estable previa o regresen a la actualización integrada en el build.

Consideraciones de migración de datos

Cambiar de canal modifica el bundle de JavaScript que ejecuta la app. Si tu app depende de migraciones o estructuras de datos incompatibles entre canales, alternar entre ellos podría causar problemas.

Por ejemplo, si una actualización beta aplica una migración de base de datos, la versión de producción podría no entender el nuevo esquema. Los desarrolladores deben asegurar que sus actualizaciones permitan cambios seguros o restringir el cambio a una sola dirección si es necesario.

Por qué el cambio de canales mejora la iteración móvil

Navegar entre canales es especialmente útil cuando necesitas revisar cambios rápidamente en un entorno de producción.

Validación rápida

Imagina una corrección urgente de un bug que necesita validarse antes de desplegarse de forma general. Con Channel Surfing, el cambio se puede aislar a un grupo pequeño de usuarios designados que pueden revisarlo antes de que llegue a producción.

Revisión de stakeholders

Un product owner o QA puede cambiar su build de producción instalado a otro canal de actualización, verificar el fix o la feature y volver a cambiar cuando termine.

Testing optimizado

Esto facilita involucrar a stakeholders no técnicos en la revisión y toma de decisiones, manteniendo un flujo de trabajo fluido. Un único build de producción se convierte en una herramienta flexible para testing, feedback y validación.

Casos de uso

Pruebas de QA: Permite al equipo de QA cambiar entre feature branches
Programas betaLos usuarios se unen al canal beta para tener acceso anticipado
Revisión de stakeholders: Los product owners previsualizan cambios antes del release
Pruebas A/B: Asigna usuarios a distintos canales para experimentos
Depuración: Cambia a un usuario específico a un canal de debug para diagnosticar problemas

Comparativa: Métodos de cambio de canal

Método	Tiempo de efecto	Persistencia en	Caso de uso
`setChannel()` del plugin	Instantáneo	Solo dispositivo (local)	Cambio de canal iniciado por el usuario
Override de dispositivo desde el Dashboard	Hasta 2 min	Base de datos del backend	Cambios de admin para dispositivos específicos
Asignación de canal API	Hasta 2 min	Base de datos del backend	Integraciones de backend automatizadas

Para una mejor experiencia de usuario al crear interfaces de cambio de canal, usa siempre el plugin de setChannel() seguro.

Buenas prácticas

Limitar el acceso: El channel surfing suele ser para uso interno; no lo expongas a todos los usuarios
Gestionar errores: Siempre gestiona los errores correctamente al cambiar de canal
Validar compatibilidad: Asegúrate de que las actualizaciones en distintos canales sean compatibles con la versión nativa instalada
Documentar canales: Mantén una documentación clara sobre el propósito de cada canal
Monitorear el uso: Rastrear qué dispositivos están en qué canales para debugging

Recursos

Conclusión

El channel surfing transforma cómo iteras en tu app Capacitor. En lugar de ver los builds de producción como endpoints fijos, se convierten en herramientas flexibles para testing, validación e iteración rápida.

Con el cambio de canal instantáneo de las últimas versiones del plugin, la experiencia es fluida: los usuarios pueden cambiar de canal y recibir actualizaciones del nuevo canal de inmediato, sin tiempos de espera.

Ya sea validando bug fixes con stakeholders, ejecutando programas beta o debugeando problemas con usuarios específicos, el channel surfing te da la flexibilidad de enviar el update correcto al usuario adecuado en el momento justo.

Continúa desde Channel Surfing para Capgo: Cómo cambiar los canales de actualización en runtime

Si estás usando Navegando entre canales en Capgo: cómo cambiar de canal de actualización en runtime 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.