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

¿Alguna vez has deseado enviar un cambio directamente a un usuario específico para recibir su feedback inmediato, sin pedirle que descargue e instale un nuevo build desde TestFlight o Google Play?

He tenido clientes que me piden mejoras que puedo implementar rápido, pero para que las validen, tenía que lanzar una actualización a todos los usuarios (arriesgado para cambios experimentales) o crear un build específico para ellos (un trabajo pesado 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 desarrollo, recopilara feedback y luego volviera a producción.

Es lo que navegación entre canales 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.

Entendiendo 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á asociada 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:

Dirigir funciones distintas a grupos de usuarios específicos
Realizar tests A/B asignando usuarios a diferentes canales
Lanzar nuevas funciones de forma gradual
Crea programas de beta testing
Depura errores de producción con usuarios específicos

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 diferentes flujos de actualización sin reinstalarse. Una app puede cambiar de canales de actualización en runtime, y seguirá recibiendo actualizaciones del nuevo canal seleccionado hasta que se desinstale o cambie a otro.

En la práctica, esto significa que un product owner o QA puede cambiar un production build a, por ejemplo, un preview canal para probar los últimos cambios. Al terminar el testing, vuelven a production de nuevo. No hace falta reinstalar ni crear un build de preview aparte.

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

Cómo implementar el cambio de canales

Antes de probar el cambio de canales, debes configurar tu proyecto con Capgo Live Updates. Para hacerlo, sigue la guía de inicio rápido de Capgo.

El único paso necesario es activar “Allow devices to self associate” en cada canal al que quieras cambiar desde el dashboard de Capgo. No se requieren más cambios de code ni modificaciones de configuración.

En esencia, el cambio de canales se gestiona con 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 la API setChannel de 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 del backend (solo lectura): Se envía una solicitud 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 almacenamiento local del dispositivo
Efecto instantáneo: La siguiente comprobación de actualizaciones usará el nuevo canal de inmediato

Antes, setChannel() se guardaba el override del canal en la base de datos del backend (como los cambios en Dashboard o API). Los dispositivos debían esperar la replicación del backend (hasta 2 minutos) para reconocer el nuevo canal. El nuevo comportamiento solo lee del backend (para validación) y guarda 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 inmediatamente, descargarlas si están disponibles y recargar la app para que el usuario entre directamente en la versió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 dividir estos pasos en varias interacciones o ejecutarlos todos a la vez. Independientemente de la estructura, asegúrate de gestionar los errores. 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 al Canales sección en tu dashboard de Capgo
Haz clic en el nombre del canal que quieras gestionar
Activar “Permitir que los dispositivos se autoasocien”
Guardar los cambios

Activa el auto-assignment en los ajustes del canal

Eso es todo. No hace falta cambiar la config de tu app. Ni defaultChannel ajustes adicionales. Solo activa el auto-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á.

Listado de canales disponibles

Puedes obtener la lista de canales disponibles para auto-asignación:

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 la auto-asignación está habilitada.

Obtener el canal actual

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

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

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

Revertir al canal por defecto

Para eliminar la sobreescritura 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 de tu config o el valor por defecto en la nube.

Cómo probar el cambio de canales

Para ver el cambio de canales 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 update.

Requisitos

El único requisito para el channel surfing es habilitar “Allow devices to self associate” en cada canal al que quieras permitir el cambio. No hace falta cambiar la config de tu app.

Crear un Test Build

Haz el build de tu app como siempre:

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 tu 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 un 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 con las OTA Updates

Ninguno es exclusivo del cambio de canales, pero suelen aparecer rápido al empezar a cambiar de canal en runtime.

Desajustes de versión en runtime

Las updates en Capgo están ligadas a las versiones nativas. Si la versión nativa de una update no coincide con la de la app instalada, no se descargará ni se aplicará. Al cambiar de canal, esto suele verse como si la app cambiara de canal pero no aplicara la update, aunque exista una disponible.

Esto suele significar que la update se publicó con 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 updates

Si una app ya descargó una update para 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 update errónea es publicar una update estable en el mismo canal. Esto crea una nueva update al principio del historial del canal, que los clientes tratarán como la última versión y aplicarán.

Capgo también ofrece un mecanismo de rollback para instruir a los clientes a reaplicar una update estable previa o volver a la update 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 reconocer el nuevo esquema. Los devs deben asegurar que sus updates sean seguros para el cambio o restringir el switch a una sola dirección si es necesario.

Por qué el 'Channel Surfing' mejora la iteración móvil

El channel surfing es especialmente útil cuando necesitas revisar cambios rápidamente en un entorno de producción.

Validación rápida

Imagina un bug fix urgente que requiere validación antes de un despliegue masivo. Con el channel surfing, el cambio puede aislarse en un grupo pequeño de usuarios designados para revisarlo antes de que llegue a producción.

Revisión de stakeholders

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

Testing optimizado

Esto facilita involucrar a stakeholders no técnicos en la revisión y toma de decisiones, manteniendo un workflow fluido. Una única 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 Beta: Los usuarios se unen al canal beta para acceso anticipado
Revisión de Stakeholders: Los product owners previsualizan cambios antes del release
Pruebas A/BAsigna usuarios a distintos canales para experimentos
DepuraciónCambia 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	Dónde se persiste	Caso de uso
`setChannel()` desde el plugin	Instantáneo	Solo en el dispositivo (local)	Cambio de canal por el usuario en la app
Override de dispositivo en 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 la mejor experiencia de usuario al crear interfaces de cambio de canal, usa siempre el setChannel() method.

Mejores prácticas

Limitar el acceso: El cambio de canales 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 los 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.

Continuamos con Channel Surfing para Capgo: Cómo cambiar de canales de Update 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 el detalle de implementación en Channels, Canales para el detalle de implementación en Channels, Canales para el detalle de implementación en Channels, Solución de beta testing para el flujo de trabajo del producto en Beta Testing Solution, y Solución de Version Targeting para el flujo de trabajo del producto en Version Targeting Solution.