Canales

¿Eres nuevo en los channels? Mira tres tutoriales cortos de canales para ver el routing por defecto, la asignación automática de dispositivos y los overrides de consola.

El @capgo/capacitor-updater métodos setChannel() y unsetChannel() en esta guía solo son compatibles con Android e iOS. No cambian el routing del canal en browser previews.

Cómo Capgo elige un canal (precedencia)

Cuando un dispositivo pide una actualización a Capgo, el canal que usará se decide en este orden (prioridad más alta primero):

1. Mapeo forzado de dispositivos: Si el ID del dispositivo se fuerza explícitamente a un canal (el Dispositivos ) en la página del canal), ese canal siempre tiene prioridad. Los mapeos forzados son overrides de console/API. Capgo los elimina 90 días después de la última escritura del override. Ver Los overrides de la consola y API expiran.
2. Override de Cloud (Dashboard o API Público): Cambiar el canal de un dispositivo en el dashboard o mediante el API Público crea un override vinculado a ese device ID. Reinstalar la app no necesitas lo limpia; borrar el override sí. Se aplica el mismo periodo de retención de 90 días.
3. Plugin setChannel() (local): En las versiones actuales del plugin, setChannel() guarda el canal en el dispositivo tras la validación del backend. No es un override del dashboard. En Android e iOS con el updater 8.51.0 o superior, persistDefaultChannelOnReinstall por defecto es true, por lo que la elección solo sobrevive a una reinstalación cuando el sistema operativo restaura los datos de la app y persistDefaultChannelOnReinstall permanece true. Llama a unsetChannel() para limpiar la elección local explícitamente.
4. configuración de Capacitor defaultChannel (valor por defecto en test build): Para builds internos / beta / test puedes configurar defaultChannel (clave legacy channel) en capacitor.config.* para que los dispositivos de test inicien en un canal de pre-release (ej. beta, pr-123). Si no existe, el dispositivo usará el default de la nube. Los builds de producción suelen dejar esto sin configurar.
5. Cloud Default Channel (estrategia principal para el ~99% de usuarios): El canal de producción principal donde aterrizan casi todos los usuarios reales. Cualquier dispositivo nuevo sin un force, sin un override, sin un local setChannel(), y sin configuración defaultChannel usa esto. Al cambiarlo, el rollout (o rollback) se aplica a todos en segundos, sin un nuevo binario.

Por qué el default de la nube es la ruta principal:

• Rollout o rollback instantáneos sin reconstruir ni republicar binarios nativos.
• Un solo lugar para gestionar el comportamiento en iOS, Android y Electron.
• Más seguro: puedes confirmar que los bundles existen y que los ajustes son correctos antes de cambiar el default.
• Cambios auditables (el equipo puede ver quién cambió qué en la UI / logs). Principio de diseño: las capas superiores (force / override / config) son excepciones (debug de un solo usuario, cambios de QA, defaults de build de prueba). Los usuarios normales pasan al default de la nube.

Cambiar el default de la nube el canal afecta a nuevo dispositivos normales que:

• No están forzados
• No tienen ya un override en la nube
• No tienen un nivel de app defaultChannel definido

Si un test build se lanza con defaultChannel: 'beta' y luego cambias el default de la nube a production, los dispositivos que empezaron en beta vía la configuración, permanecerán así hasta que se aplique una asignación de mayor prioridad o hasta que lances un binario sin defaultChannel. Eliminar un force, cloud override o local setChannel() no quita el valor de la config; ese fallback persiste hasta el nuevo binario.

Los dispositivos se mantienen en su canal actual a menos que:

• Los fuerces a otro canal (vía consola o Public API).
• Cambies el cloud override en el dashboard o en Public API.
• Llama a setChannel() (asignación local en versiones actuales del plugin).
• Elimines o archives el canal en el que están (entonces aplicarán el fallback por precedencia en el próximo check).
• Esperes a que un override de consola/API expire tras 90 días.
• Llama a unsetChannel() para limpiar una local setChannel() assignment. Esto no elimina un override de consola/API ni uno configurado en la app defaultChannel; se aplica de nuevo la precedencia normal.
• Reinstala la app, lo que puede borrar una asignación local en versiones antiguas del updater o cuando no se restauran los datos de la app. En Android e iOS con el updater 8.51.0 o superior, persistDefaultChannelOnReinstall por defecto es true, por lo que los datos restaurados de la app solo preservarán la elección local mientras esta opción esté activa trueLas anulaciones de Console/API no se ven afectadas.

Si un canal está desactivado para una plataforma (mira los interruptores de iOS / Android / Electron) y de otro modo habría sido seleccionado, la selección lo omite y recurre a la siguiente regla.

Nota: Configurar defaultChannel significa que cambiarlo requiere un nuevo binario; úsalo con intención para test/QA, no para el control general de producción.

Ejemplo de configuración de Capacitor

capacitor.config.ts

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

Si más adelante cambias el valor por defecto del dashboard a production, los dispositivos que ya estén en otro canal (vía config, override o force) NO se moverán automáticamente; solo los dispositivos nuevos (o aquellos a los que les elimines el override/force) lo adoptarán.

---

Gestión de canales

Primero, echemos un vistazo a la página de canales. Puedes acceder haciendo clic en tu app y luego haciendo clic en la pestaña Canales.

Crear un canal

Como puedes ver, hay un botón + en la esquina inferior derecha. (1 en la imagen) Al hacer clic en él, se abrirá un modal donde podrás crear un nuevo canal.

Luego, tras hacer clic en Add debería aparecer un nuevo canal en la lista.

¿Qué significa “mal configurado”?

A veces, la configuración de un canal no es válida. En ese caso, verás un aviso importante y la Misconfigured columna indicará Yes en uno o más canales. Puedes obtener más información al respecto aquí

Eliminar un canal

Para eliminar un canal desde la web app, abre la Canales pestaña de tu app y busca la fila del canal. En la Acción columna, haz clic en el icono de la papelera y luego en Eliminar en el cuadro de confirmación.

Si el icono de la papelera no es visible, tu cuenta no tiene channel.delete permisos para esa app. Pide a un admin de la organización o de la app un rol con permiso para eliminar canales, o elimina el canal con una clave API que tenga el permiso:

npx @capgo/cli@latest channel delete <channel-name> <app-id>

Vinculado a una organización y a una app Preview de app puede eliminar de forma atómica solo el canal de preview no público y el bundle que creó con channel delete <preview-channel> <app-id> --delete-bundle. No puede cambiar ni eliminar un canal default/main existente, el canal de otra clave de preview o el bundle de otra clave. Consulta Claves de API para la configuración de mínimos privilegios.

Gestión de un canal

Haz clic en el nombre del canal para abrir su página. Es una página completa con pestañas, no un modal.

Pestañas del canal

• Dashboard: Estadísticas de adopción del bundle actual e instalaciones para este canal.
• InformaciónConfiguración de canales detallada abajo, además de rollout progresivo y Test Update API.
• Dispositivos: Mapeos forzados creados solo desde la consola o desde Public API. No lista todos los dispositivos que están actualmente en el canal ni los dispositivos que usaron setChannel(). Los overrides de la consola y API expiran.
• Historial: Cambios de configuración y de bundle para este canal.
• Vista previa: Vista previa nativa y en el navegador del bundle vinculado. Activa la vista previa en Información de la app primero.

Configuración de información

Mantente en la Información pestaña. Los ajustes aparecen en este orden:

Primero, Canal de descarga por defecto es un badge de estado, no un toggle. Activo significa que este canal es el predeterminado en la nube para nuevos dispositivos. Haz clic Gestionar en Ajustes de la app para cambiar el valor predeterminado en Información de la app. Para valores predeterminados por plataforma (uno para iOS, uno para Android y uno para Electron), consulta esa misma sección.

Segundo, el IOS configuración. Si esto es falso, los dispositivos iOS no podrán descargar actualizaciones de este canal.

Tercero, el Android configuración. Si esto es falso, los dispositivos Android no podrán descargar actualizaciones de este canal.

Cuarto, el Electron ajuste. Si es false, las apps de Electron no podrán descargar actualizaciones de este canal.

Quinto, el Disable auto downgrade under native configuración. Si esto es true, será imposible hacer un downgrade desde una versión nativa. Esto significa que si has subido una 1.2.0 versión a la App Store o Play Store e intentas establecer la versión del canal en 1.1.0 entonces la actualización (downgrade) fallará.

Sexto es el Disable auto update. Esta configuración es bastante compleja; puedes aprender más sobre ella en aquí

Séptimo es el ajuste Download format . Define si los dispositivos descargan un zip completo, solo los archivos delta modificados o lo mejor de ambos. Consulta Formato de descarga.

Octavo es Allow development build. Si esto es true, se permitirá que los development builds descarguen actualizaciones de este canal. Si no, cualquier solicitud de actualización que tenga prod establecido en false será rechazada. Esto es útil principalmente para pruebas.

El noveno es Allow production build. Si esto es falso, las builds de producción (store) no recibirán actualizaciones de este canal. Mantén esta opción activada para canales que sirvan a usuarios reales.

El décimo es el Allow Emulators. Si esto es falso, Capgo rechazará cualquier solicitud de actualización proveniente de un emulador. Esto es útil principalmente para realizar pruebas.

El undécimo es Allow physical devices. Si es falso, Capgo rechazará las solicitudes de actualización de teléfonos y tablets reales. Actívalo en canales de producción.

El duodécimo es Allow devices to self dissociate/associate. Si es verdadero, el setChannel el método estará disponible en Android e iOS. Si esto se establece en false e intentas llamar a setChannel con este canal, la llamada fallará.

Prueba de actualización API

Al final de la Información pestaña, expande Prueba de actualización API. Capgo muestra un comando curl para /updates un dispositivo de muestra en este canal.

Los cambios pueden tardar hasta 60 segundos en verse en el API debido al caché. Si no se puede probar el canal, la consola te avisará: el canal necesita al menos una plataforma (iOS o Android), builds de producción, dispositivos físicos y ser el canal de descarga por defecto o permitir la autoasignación de dispositivos.

Enviar notificación de update

Después de cambiar el bundle vinculado, la consola puede pedirte Enviar notificación de actualización. Eso encola un push silencioso para que los dispositivos del canal busquen el nuevo bundle ahora. Primero configura las credenciales de push de Android e iOS en la pestaña Notifications de la app.

Los overrides de la consola y API expiran

Se eliminan los mappings forzados y los overrides de canal de API en el Dashboard/Público 90 días después de la última escritura de override. El último check-in del dispositivo no reinicia ese reloj. Para una asignación que sobreviva a esa limpieza, establece defaultChannel en tu configuración de Capacitor (se mantiene tras reinstalar, requiere un nuevo binario para cambiar) o llama a setChannel() desde una app de Android o iOS usando @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, o 8.0.0+ para la versión mayor de tu plugin. Estas versiones guardan la asignación localmente, evitando la limpieza de 90 días. Las versiones anteriores escriben un override en el backend sujeto a la misma limpieza. En Android e iOS con el updater 8.51.0 y posteriores, persistDefaultChannelOnReinstall por defecto es true, por lo que una selección local solo sobrevivirá a una reinstalación si el sistema operativo restaura los datos de la app y persistDefaultChannelOnReinstall se mantiene true. Una reinstalación con persistDefaultChannelOnReinstall: false puede borrar esa selección local incluso si se restauran los datos de la app. Usa unsetChannel() para borrar esa selección local de forma explícita.

Sobrescribe la retención en la pestaña Devices del canal. Aparecerá el mismo aviso cuando fuerces un ID de dispositivo en el canal.

Esto es independiente de la retención del inventario de dispositivos. El inventario elimina los dispositivos que no se han conectado a Capgo en 90 días. El override de limpieza elimina el mapeo aunque el dispositivo siga activo. Detalles completos: Los overrides de Console y API caducan tras 90 días.

Formato de descarga

Abre un canal y quédate en el Información . Formato de descarga está en la lista de ajustes, bajo Disable auto update.

Download format en la pestaña Information del canal. Los canales nuevos usan Zip + delta por defecto.

Este ajuste elige qué envía Capgo cuando un dispositivo en este canal busca una actualización. Deja Zip + delta a menos que necesites forzar un tipo.

Etiqueta en la consola	Valor de CLI / API	Qué descargan los dispositivos
Zip + delta (por defecto)	all	Cada dispositivo recibe el mejor paquete compatible. Los dispositivos con una versión del plugin que soporta Delta solo descargan los archivos delta modificados cuando el bundle los incluye. Solo los dispositivos con una versión antigua del plugin sin soporte para Delta, o los bundles subidos sin archivos delta, recurrirán al zip completo.
Solo zip completo	zip	Cada dispositivo descarga el zip completo del bundle, incluso si existen archivos delta.
Solo delta	delta	Solo los archivos delta modificados. Los dispositivos con una versión antigua del plugin sin soporte para Delta seguirán recibiendo el zip completo cuando el bundle lo incluya.
Solo zip completo desde la build de la store	zip_from_builtin	Solo zip completo mientras el dispositivo siga en la build de la store. Tras el primer live update, Capgo volverá a servir zip + delta.
Solo delta desde la build de la store	delta_from_builtin	Solo delta mientras el dispositivo siga en la build de la store. Tras el primer live update, Capgo volverá a servir zip + delta.

Con Zip + delta, es normal ver algunas descargas de zip completo. Ocurre en dispositivos con un Native Build antiguo y una versión de plugin sin soporte para Delta (inferior 5.10.0, 6.25.0, o 7.0.35 a su versión principal). Consulta Actualizaciones delta.

El build de la tienda son los assets web incluidos en el binario de App Store o Play Store, antes de cualquier actualización de Capgo. Usa un from store build only modo cuando la primera actualización tras la store build deba ser solo zip completo o solo delta, permitiendo ambos en actualizaciones posteriores.

Capgo no emparejará un canal de solo zip con un bundle de solo delta, ni viceversa. La consola, CLI y Canales API rechazará el guardado y te pedirá que subas el paquete faltante o cambies el modo.

Puedes configurar el mismo valor desde CLI. El canal ya debe existir:

npx @capgo/cli@latest channel set production com.example.app --update-package zip

Valores válidos: all, zip, delta, zip_from_builtin, delta_from_builtin.

Despliegues progresivos

La pestaña Información del canal incluye una sección de Rollout progresivo sección con Objetivo del rollout y Fallback estable, Cambiar el objetivo de rollout, Aplicar porcentaje, y acciones Completar rollout, Rollback del rollout, Activar rollout, Desactivar rollout, Pausar rollout, y Reanudar rollout.

Los controles de rollout progresivo aparecen en la pestaña Information del canal.

Consulta la Despliegues progresivos antes de habilitar uno. Esa guía cubre el enrutamiento de upload (Auto (recomendado) / Objetivo del rollout / Reemplazar estable; CLI --stable / API target: "stable" para sobrescribir), el Este canal usa despliegue progresivo diálogo de bundle-link y un flujo de trabajo seguro con Observe y Análisis de logs.

Continuar desde Channels

Si estás usando Canales 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, Solución de beta testing para el flujo de trabajo de producto en Beta Testing Solution, Solución de segmentación por versión para el flujo de trabajo de producto en Version Targeting Solution, y Buenas prácticas de entornos Capgo: Staging con un único App ID móvil para el contexto práctico en Capgo Environment Best Practices: Staging with One Mobile App ID.