Canales
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
¿Nuevo en canales? Mira tres breves tutoriales de canales para ver la enrutación predeterminada, la autoasignación de dispositivos y las anulaciones de consola en acción.
El @capgo/capacitor-updater métodos setChannel() y unsetChannel() en esta guía solo se admiten en Android e iOS. No cambian la enrutación de canales en las vistas previas del navegador.
Cómo Capgo elige un canal (precedencia)
Sección titulada “Cómo Capgo elige un canal (precedencia)”Cuando un dispositivo solicita una actualización a Capgo, el canal que utilizará se decide en el siguiente orden (de mayor a menor prioridad):
- Mapeo forzado de dispositivos: Si el ID del dispositivo se fuerza explícitamente a un canal (el Dispositivos pestaña en la página del canal), ese canal siempre tiene prioridad. Las asignaciones forzadas son sobrescrituras de la consola/API. Capgo las elimina 90 días después de la última escritura de sobrescritura. Ver Los overrides de la consola y API expiran.
- Sobrescritura en la nube (Dashboard o API pública): Cambiar el canal de un dispositivo en el dashboard o a través de la API pública escribe una sobrescritura vinculada a ese ID de dispositivo. Reinstalar la app no necesitas la borra; eliminar la sobrescritura sí. Se aplica la misma retención de 90 días.
- Plugin
setChannel()(local): En las versiones actuales del plugin,setChannel()guarda el canal en el dispositivo tras la validación del backend. No es una sobrescritura del dashboard. En Android e iOS con updater 8.51.0 o posterior,persistDefaultChannelOnReinstallpor defecto estrue, por lo que la elección solo sobrevive a una reinstalación si el sistema operativo restaura los datos de la app ypersistDefaultChannelOnReinstallse mantienetrue. Llama aunsetChannel()para borrar explícitamente la elección local. - la config de Capacitor
defaultChannel(build de test por defecto): Para builds internos / beta / de test puedes configurardefaultChannel(clave legacychannel) encapacitor.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. - Cloud Default Channel (estrategia principal para el ~99% de los usuarios): El canal de producción principal al que llegan prácticamente todos los usuarios reales. Cualquier dispositivo nuevo sin un force, sin un override, sin un local
setChannel(), y sin configuracióndefaultChannelusa 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 nuevos dispositivos normales que:
- No están forzados
- No tienen todavía un override en la nube
- No tienen un override a nivel de app
defaultChanneldefinido
Si un build de prueba se publica 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 una fuerza, una superposición en la nube o una local setChannel() no elimina el valor de la configuración; ese fallback permanece hasta el nuevo binario.
Los dispositivos permanecen en su canal actual a menos que:
- Los fuerces a otro canal (consola o API público).
- Cambia el override de la nube en el dashboard o en el API público.
- Llama a
setChannel()(asignación local en las versiones actuales del plugin). - Elimines o archives el canal en el que están (luego volverán a aplicar la precedencia en la siguiente comprobación).
- Esperes a que un override de consola/API expire tras 90 días.
- Llama a
unsetChannel()para borrar una asignación localsetChannel()asignación. Esto no elimina un override de console/API ni una configurada en la appdefaultChannel; vuelve a aplicarse 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 updater 8.51.0 o posterior,
persistDefaultChannelOnReinstallpor defecto estrue, de modo que los datos restaurados de la app solo conserven la elección local mientras esta opción permanezcatrue. Los overrides de console/API no se ven afectados.
Si un canal está deshabilitado para una plataforma (ver toggles de iOS / Android / Electron) y de otro modo se habría seleccionado, la selección lo omite y pasa a la siguiente regla.
Nota: Establecer
defaultChannelsignifica que cambiarlo requiere un nuevo binario; úsalo a propósito para pruebas/QA, no para el control general de producción.
Ejemplo de configuración de Capacitor
Sección titulada “Ejemplo de configuración de Capacitor”// 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
Sección titulada “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
Sección titulada “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”?
Sección titulada “¿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
Sección titulada “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 diálogo de confirmación.

Si el icono de la papelera no aparece, tu cuenta no tiene channel.delete permisos para esa app. Pide a un admin de la organización o de la app que te asigne un rol que pueda 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 una app Preview de app key puede eliminar de forma atómica solo el canal de vista previa no público y el bundle que creó channel delete <preview-channel> <app-id> --delete-bundle. No puede modificar ni eliminar un canal default/main existente, el canal de otra clave de preview ni el bundle de otra clave. Ver Claves de API para la configuración de privilegios mínimos.
Gestión de un canal
Sección titulada “Gestión de un canal”Haz clic en el nombre del canal para abrir la página del canal. Es una página completa con pestañas, no un modal.

Pestañas del canal
Sección titulada “Pestañas de canales”- 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 en el navegador y nativa del bundle vinculado. Activa la vista previa del bundle en Información de la app primero.
Ajustes de información
Sección titulada “Configuración de información”Mantente en la Información pestaña. La configuración aparece en este orden:
Primero, Canal de descarga predeterminado 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 setting. Si es true, no será posible hacer downgrade desde una versión nativa. Esto significa que si has subido un 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á.
La sexta es la Disable auto update. Esta configuración es bastante compleja y puedes aprender más al respecto aquí
La séptima es la Download format configuración. Elige si los dispositivos descargan un zip completo, solo los archivos delta modificados o lo mejor de ambos. Ver Formato de descarga.
La octava es Allow development build. Si es true, las builds de desarrollo podrán descargar actualizaciones de este canal. Si no, cualquier solicitud de actualización que tenga prod configurar en false será rechazado. Esto es útil principalmente para fines de prueba.
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á.
Probar actualización API
Sección titulada “Test Update API”En la parte inferior de la Información pestaña, expande Probar actualización API. Capgo muestra un comando curl contra /updates para un dispositivo de ejemplo en este canal.
Los cambios pueden tardar hasta 60 segundos en aparecer en API debido a la caché. Si el canal no se puede probar, 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 predeterminado o permitir la autoasignación de dispositivos.
Enviar notificación de actualización
Sección titulada “Enviar notificación de actualización”Después de cambiar el bundle vinculado, la consola puede pedirte que Enviar notificación de actualización. Eso encola un push silencioso para que los dispositivos del canal busquen el nuevo bundle ahora. Configura antes las credenciales de push de Android e iOS en la pestaña Notificaciones de la app.
Los overrides de la consola y API expiran
Sección titulada “La consola y las anulaciones de API caducan”Se eliminan las mapeos forzados y las sobrecargas de canales API en Dashboard/Público 90 días después de la última escritura del override. El último check-in del dispositivo no reinicia ese contador. Para que una asignación sobreviva a esa limpieza, configura defaultChannel en tu configuración de Capacitor (persiste tras la reinstalación, requiere un nuevo binario para modificarla) o llamar setChannel() desde una app Android o iOS usando @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, o 8.0.0+ para la versión principal de tu plugin. Estas versiones almacenan la asignación localmente, lo que evita la limpieza de 90 días. Las versiones anteriores escriben una sobrescritura en el backend sujeta a la misma limpieza. En Android e iOS con updater 8.51.0 o posterior, persistDefaultChannelOnReinstall por defecto es true, por lo que una selección local solo puede sobrevivir a una reinstalación si el sistema operativo restaura los datos de la aplicación 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 aplicación. Usa unsetChannel() para borrar esa selección local explícitamente.

Esto es independiente de la retención del inventario de dispositivos. Inventory elimina los dispositivos que no se han conectado a Capgo durante 90 días. La limpieza de override elimina el mapeo incluso si el dispositivo sigue activo. Detalle completo: Los overrides de Console y API caducan tras 90 días.
Formato de descarga
Sección titulada “Formato de descarga”Abre un canal y permanece en la Información . Formato de descarga está en la lista de ajustes, en Desactivar actualización automática.

Este ajuste define lo que Capgo envía cuando un dispositivo de 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. Provienen de dispositivos que aún ejecutan un build nativo antiguo con una versión del 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 el build de tienda deba ser solo zip completo o solo delta, y las siguientes puedan usar ambos.
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 zipValores válidos: all, zip, delta, zip_from_builtin, delta_from_builtin.
Despliegues progresivos
Sección titulada “Rollouts 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 objetivo de rollout, Aplicar porcentaje, y acciones Completar rollout, Rollback del rollout, Activar rollout, Desactivar rollout, Pausar rollout, y Reanudar rollout.

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
Sección titulada “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 del producto en Beta Testing Solution, Solución de segmentación por versión para el flujo de trabajo del 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 Buenas prácticas de entornos: staging con un solo ID de app móvil.