Saltar al contenido
Capgo - Actualizaciones en vivo para Capacitor Apps Capgo

Canales

Un canal Live Update apunta a una construcción de paquete JS específica de tu aplicación que se compartirá con cualquier dispositivo configurado para escuchar ese canal de actualizaciones. Cuando instales el Capgo Live Updates SDK en tu aplicación, cualquier binario nativo configurado a ese canal verificará actualizaciones disponibles cada vez que se lance la aplicación. Puedes cambiar la construcción a la que apunta un canal en cualquier momento y también puedes retroceder a versiones anteriores si es necesario.

¿Cómo un dispositivo elige un canal (precedencia)?

Sección titulada “¿Cómo un dispositivo elige un canal (precedencia)?”

Cuando un dispositivo busca una actualización, Capgo decide qué canal usar en este orden estricto (prioridad más alta primero):

  1. Mapeo de dispositivo forzado (Panel de control) – Asigna manualmente un ID de dispositivo específico a un canal. Utilice para depuración urgente o pruebas controladas con un solo usuario real. Esto siempre gana. Capgo elimina la asignación 90 días después de la última escritura de sobrescritura. Consulte Console y API sobrescriben expiran después de 90 días.
  2. Cloud override (por dispositivo) a través de la consola o API – Creada cuando cambies el canal del dispositivo en el panel de control o a través de API. Utilice para usuarios de QA que cambian entre canales de características / PR o para reproducir un problema de usuario. Reinstalar el binario no elimina la sobrescritura; eliminar la sobrescritura del dispositivo lo hace. La misma retención de 90 días se aplica.
  3. Plugin setChannel() Canal local – Creado cuando la aplicación llama a setChannel() y el servidor de backend valida que el canal objetivo permite la autoasignación. El canal seleccionado se almacena localmente en ese dispositivo, tiene efecto instantáneamente y no se muestra en la interfaz de usuario de Sustitución de Dispositivo.
  1. Capacitor de configuración defaultChannel (versión de prueba predeterminada) – Si está presente en capacitor.config.* y no existe un canal forzado/override/local, la aplicación arranca en este canal (por ejemplo, beta, qa, pr-123Para versiones de prueba / internas, los pruebas se dirigen automáticamente a un canal de prelanzamiento. Las versiones de producción suelen dejar esto sin configurar.
  2. Canal por defecto de la nube (ruta principal ~99% de usuarios) – Si marca un canal por defecto en la consola, todos los usuarios normales (sin forzar, sin override de la consola/API, sin canal local de plugin, sin configuración defaultChannel) se unen aquí. Cambiarlo para desplegar o retroceder instantáneamente—sin nuevo binario. Si tiene valores por defecto específicos de plataforma (por ejemplo, uno solo para iOS, uno solo para Android, uno solo para Electron), cada dispositivo aterriza en el valor por defecto que coincide con su plataforma. Dejar el canal por defecto de la nube sin configurar está permitido; en ese caso, el dispositivo debe coincidir con los pasos 1-4 para recibir actualizaciones.

Buena práctica:

  • Tener en cuenta 1-4 como capas de excepción / pruebas; cuando establezca un canal por defecto en la nube, los usuarios reales deben fluir hacia él. Si no lo configura, sea deliberado sobre cómo los usuarios se unen (normalmente a través de defaultChannel in config or per-device overrides).
  • Configuración solo para defaultChannel en binarios que envíes explícitamente a los probadores. Dejarlo sin configurar mantiene la lógica de producción centralizada en la consola.
  • Use setChannel() con moderación en producción—principalmente para pruebas de QA o diagnósticos dirigidos.

Si un canal está deshabilitado para la plataforma (iOS/Android/Electron) cuando de lo contrario sería elegido, el proceso de selección lo omite y continúa con la lista.

Resumen: Obligatorio > Consola/API Sustitución > Plugin setChannel() canal local > Configuración defaultChannel > Por defecto de la nube.

Los registros y las API sobrescripciones caducan después de 90 días

Título de la sección “Consola y API expiran después de 90 días”

Para los mapeos forzados y las sobrescripciones de canal de Dashboard o Público API se almacenan como asignaciones por dispositivo en Capgo. Un trabajo de limpieza elimina esas asignaciones. 90 días después de la última escritura de overrideVerificando la actualización no reinicia el temporizador. Solo escribiendo nuevamente la sobrescritura (o eliminándola tú mismo) cambia la fecha de modificación.

Esto no es lo mismo que retención de inventario de dispositivosInventario elimina dispositivos que no se han conectado a Capgo durante 90 días. Sustituye la limpieza elimina la asignación incluso si el dispositivo sigue activo.

Para una asignación que no se elimina mediante esta limpieza:

  • Establecer defaultChannel en capacitor.config.* (sobrevive a la reinstalación; requiere un nuevo binario nativo para cambiar más tarde).
  • Call setChannel() from the app. On plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 and later, that assignment is local and is not removed by this cleanup. Reinstalling the app clears it, so the app must call setChannel() si quieres ese canal de nuevo.

El canal Dispositivos pantalla de consola y el dispositivo Opción de interfaz de usuario solo lista asignaciones y públicas API no listan todos los dispositivos en el canal, y no listan dispositivos locales setChannel() assignments.

El canal Capgo de dispositivos mostrando el popover de retención personalizada: las sobrescripciones del console caducan después de 90 días
Ocultar notificación de retención en la pestaña dispositivos del canal.

Sección titulada “Comportamiento de canal predeterminado”

Comportamiento del canal por defecto

Setting a cloud default is optional, but it usually serves as the catch-all path for new devices. Without one, only devices that match on forced mappings, overrides, or a defaultChannel En la configuración Capacitor recibirán actualizaciones. Cuando marques los valores por defecto, ten en cuenta estos patrones.

  • Valores predeterminados específicos de plataforma – Si un canal tiene iOS, Android y Electron habilitados, se convierte en el único predeterminado; cualquier dispositivo sin sobreescribir se unirá aquí.
  • Preferencias por plataforma por defecto – Si divide los canales por plataforma (por ejemplo, ios-production con solo iOS habilitado, android-production con solo Android habilitado, y electron-production con solo Electron habilitado), marca cada uno como predeterminado para su plataforma. Los dispositivos iOS van al predeterminado de iOS, los dispositivos Android van al predeterminado de Android, y las aplicaciones Electron van al predeterminado de Electron.

Recuerde que el predeterminado de la nube y defaultChannel en capacitor.config.* ocupan el mismo nivel de decisión. Si establece un predeterminado de nube, no necesita duplicar el valor en su configuración Capacitor —deje defaultChannel vacío para ediciones de producción. Reserve defaultChannel para binarios que envíe intencionalmente a los probadores o QA cuando desee que comiencen en un canal no de producción incluso si el predeterminado de la nube es diferente.

Puede cambiar los predeterminados en cualquier momento en la consola. Abra el canal, luego Gestionar en configuración de la aplicación, lo que te lleva a Información de la AplicaciónLa configuración predeterminada ya no es un interruptor en la página del canal. Cuando intercambies una configuración predeterminada, los nuevos dispositivos siguen la nueva configuración de inmediato y los dispositivos existentes siguen las reglas de precedencia normales la próxima vez que se conecten.

Configuración de un Canal

Título de la sección “Configuración de un Canal”

Durante el proceso de incorporación, creas el primer canal (la mayoría de los equipos lo llaman “Producción”), pero nada está bloqueado—puedes renombrar o eliminar cualquier canal en cualquier momento. Para agregar canales adicionales más tarde:

  1. Dirígete a la sección “Canales” de la consola de Capgo
  2. Haz clic en el botón “Nuevo Canal”
  3. Ingresa un nombre para el canal y haz clic en “Crear”

Los nombres de los canales pueden ser cualquier cosa que desees. Una estrategia común es que los canales se ajusten a las etapas de desarrollo, como:

  • Development - para probar actualizaciones en vivo en dispositivos locales o emuladores
  • QA - for your QA team to verify updates before wider release
  • Staging para pruebas finales en un entorno similar a la producción
  • Production - para la versión de tu aplicación que los usuarios finales reciben desde las tiendas de aplicaciones.

Configurando el canal en tu aplicación.

Título de la sección “Configurando el canal en tu aplicación”.

Una vez creados los canales, debes configurar tu aplicación para que escuche el canal adecuado. En este ejemplo, utilizaremos el Development canal.

Abre tu capacitor.config.ts (o capacitor.config.jsonarchivo. Debajo de plugins ) archivo. Bajo la defaultChannel for para (Internal / QA). Para compilaciones de producción, prefiere omitirla para que los dispositivos utilicen el valor por defecto de Cloud a menos que se sobrescriba explícitamente.

import { CapacitorConfig } from '@capacitor/cli';


const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

En primer lugar, construye tu aplicación web y ejecuta npx cap sync para copiar el archivo de configuración actualizado a tus proyectos de iOS, Android y Electron. Si omites este paso de sincronización, tus proyectos nativos seguirán utilizando el canal en el que estaban configurados anteriormente.

Opciones y estrategias de canal

Sección titulada “Opciones y estrategias de canal”

Los canales tienen varias opciones que controlan quién puede recibir actualizaciones y cómo se entregan las actualizaciones. Los más importantes están a continuación. Puede configurar estos desde la aplicación web, el CLI, o el Public API.

  • Canal predeterminado: Opcionalmente, marca los canales o plataformas específicas a los que se conectan nuevos dispositivos. En la consola, esto se encuentra en Información de la aplicación ("Gestionar en ajustes de la aplicación desde la página del canal). Consulte “Comportamiento del canal predeterminado” para escenarios de enrutamiento.
  • Filtros de plataforma: Habilitar o deshabilitar la entrega a iOS, Androido Electron dispositivos por canal.
  • Deshabilitar la actualización automática bajo nativo: Evita enviar una actualización cuando la versión nativa del dispositivo es más nueva que la versión del paquete del canal (por ejemplo, dispositivo en 1.2.3 mientras que el canal tiene 1.2.2).
  • Allow development builds: Permit updates to development builds (useful for testing). CLI: --dev / --no-dev.
  • Allow production builds: Permit updates to production (store) builds. Leave this on for channels that serve real users. CLI: --prod / --no-prod.
  • Permitir dispositivos emuladores: Permite actualizaciones a emuladores/simuladores (útil para pruebas). CLI: --emulator / --no-emulator.
  • Permitir dispositivos físicos: Permite actualizaciones a teléfonos y tabletas reales. Dejar esto encendido para canales de producción. CLI: --device / --no-device.
  • Permitir la asignación automática del dispositivo: permite que la aplicación cambie a este canal en tiempo de ejecución setChannelSi se deshabilita, setChannel fallará para este canal. CLI: --self-assign / --no-self-assign.
  • Formato de descarga: Elija si los dispositivos descargan un archivo zip completo, solo los archivos delta modificados o la mejor de ambos (all, zip, delta, zip_from_builtin, delta_from_builtin). See Descargar formato para el menú desplegable de la consola y cuando cada modo es útil.

Actualizaciones progresivas

Sección titulada “Despliegue progresivo”

Un canal puede mantener un paquete estable mientras expone gradualmente un objetivo de despliegue separado a un cohorte de dispositivos pegados. Puede pausar, reanudar, promover, retroceder y configurar una respuesta de fallo automática sin cambiar el canal para todos. Consulte Despliegues progresivos para el modelo de entrega, flujo de trabajo de la consola, API campos y CLI comandos.

Deshabilitar estrategias de Actualización Automática

Deshabilitar estrategias de actualización automática

Utilice esto para restringir qué tipos de actualizaciones entregará el canal automáticamente. Opciones:

  • mayor: Bloquea un paquete objetivo cuya versión mayor es superior a la base de línea nativa del dispositivo (version_build) Ejemplo: 1.2.3 -> 2.0.0 está bloqueado; 1.2.3 -> 1.9.0 está permitido.
  • menor: Bloquea un paquete objetivo cuya versión mayor o menor difiere de version_buildEjemplo: 1.2.3 -> 1.3.0 está bloqueado; 1.2.3 -> 1.2.4 se permite.
  • patch: Modo más estricto. Bloquea cualquier cambio a un número mayor, menor o de parche. Solo se permiten cambios de sufijo mientras MAJOR.MINOR.PATCH se mantiene igual. Ejemplos: 1.0.0-beta.1 -> 1.0.0-beta.2 Está permitido. 1.0.0+build.1 -> 1.0.0+build.2 Está permitido. 1.0.0 -> 1.0.1 está bloqueado.
  • metadata: Requiere una versión de actualización mínima de metadatos en cada paquete. Configure mediante CLI utilizando --min-update-version o --auto-min-update-versionEstas estrategias comparan el paquete objetivo del canal con la base nativa enviada como
  • none: Permitir todas las actualizaciones según compatibilidad semver.

Estas estrategias comparan el paquete objetivo del canal con la base nativa enviada como version_buildno, la versión descargada actualmente enviada como version_name.

Aprenda más detalles y ejemplos en la estrategia de deshabilitar actualizaciones en /docs/cli/comandos/#desactivar-actualizaciones-estrategia.

Ejemplo (CLI). El canal debe existir ya (no lo crea):channel set ventana de terminal

Copiar a portapapeles
# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major


# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign


# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

Sección titulada “Usando setChannel() desde Tu Aplicación”

Usando setChannel() desde tu aplicación

The setChannel() El método permite que su aplicación cambie programáticamente entre canales en tiempo de ejecución. Esto es especialmente útil para:

  • Menús de depuración QA donde los probadores pueden cambiar entre canales
  • Flujos de inscripción en el programa beta
  • Implementaciones de banderas de características
  • Escenarios de pruebas A/B
import { CapacitorUpdater } from '@capgo/capacitor-updater';


// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });


// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

Asignar un paquete a un canal

Sección titulada “Asignar un paquete a un canal”

Para desplegar un live update, debes subir una nueva compilación de paquete de JS y asignarla a un canal. Puedes hacer esto en un paso con el Capgo CLI:

ventana de terminal
npx @capgo/cli@latest bundle upload --channel=Development

Esto subirá tus activos web compilados y establecerá la nueva compilación como la build activa para el Development canal. Cualquier aplicación configurada para escuchar ese canal recibirá la actualización la próxima vez que busque una.

También puede asignar compilaciones a canales desde la sección "Paquetes" del panel de control Capgo. Haga clic en el icono de menú junto a una compilación y seleccione "Asignar a canal" para elegir el canal para esa compilación.

Versión de paquetes y canales

Sección titulada "Versión de paquetes y canales"

Es importante tener en cuenta que los paquetes en Capgo son globales para tu aplicación, no específicos de canales individuales. El mismo paquete puede asignarse a varios canales.

Al versionar tus paquetes, recomendamos utilizar versión semántica con el Semver Tester de Capgo y identificadores de pre-lanzamiento para compilaciones específicas de canales. Por ejemplo, un lanzamiento beta podría versionarse como 1.2.3-beta.1.

En CI, si la versión local ya se había subido, utilice npx @capgo/cli@latest bundle upload --auto-bump opcionalmente major, minor, patch/fix, metadata, o ai) para que CLI incremente desde el paquete vinculado del canal hasta encontrar un nombre libre. Con ai, Workers AI infiere el nivel desde el delta de manifestos local vs previo (cae en patch con ninguna versión previa Capgo). No puede combinarse con --bundle. Consulte Integración CI/CD y el CLI referencia.

Este enfoque tiene varios beneficios:

  • Esta aproximación tiene varios beneficios: 1.2.3-beta.1 Claramente comunica la relación entre las compilaciones. 1.2.3.
  • Permite reutilizar números de versión entre canales, reduciendo la confusión.
  • Permite reutilizar números de versión en diferentes canales, reduciendo la confusión. 1.2.3, sabes 1.2.2 , sabe que es la versión estable anterior.

Aquí hay un ejemplo de cómo podrías alinear las versiones de tu paquete con una configuración de canal típica:

  • Development canal: 1.2.3-dev.1, 1.2.3-dev.2, etc.
  • QA canal: 1.2.3-qa.1, 1.2.3-qa.2, etc.
  • Staging canal: 1.2.3-rc.1, 1.2.3-rc.2, etc.
  • Production canal: 1.2.3, 1.2.4, etc.

Usando semver con identificadores de pre-lanzamiento es un enfoque recomendado, pero no estrictamente necesario. La clave es encontrar un esquema de versionado que comunique claramente las relaciones entre tus compilaciones y se alinee con el proceso de desarrollo de tu equipo.

Revertir una Live Update

Sección titulada “Revertir una Live Update”

Si despliega una live update que introduce un error o necesita ser revertido, puede revertir fácilmente a una versión anterior. Desde la sección “Canales” de la consola:

  1. Click en el nombre del canal que desea revertir
  2. Encuentre la versión que desea revertir y haga clic en el icono de la corona Revertir versión
  3. Confirmar la acción

La versión seleccionada se convertirá inmediatamente en la versión activa para ese canal nuevamente. Las aplicaciones recibirán la versión revertida la próxima vez que busquen una actualización.

Automatizando Despliegues

Sección titulada “Automatizando Despliegues”

Para flujos de trabajo más avanzados, puede automatizar los despliegues de su live update como parte de su pipeline CI/CD. Al integrar Capgo en su proceso de compilación, puede subir automáticamente nuevos paquetes y asignarlos a canales cada vez que pulse en ciertas ramas o cree nuevas versiones.

Consulte el Integración CI/CD docs to learn more about automating Capgo live updates.

Previsualizaciones de PR con privilegios mínimos

Previsualizaciones de PR con privilegios mínimos

Utilice un App Preview API clave cuando la CI necesite una canal temporal por solicitud de extracción, pero no deba gestionar canales existentes principales/por defecto. La clave permanece vinculada a la organización propietaria y la aplicación seleccionada; simplemente no tiene ningún papel organizativo. Cada canal de previsualización no público que crea recibe sus propias autorizaciones de ciclo de vida automáticas, escaladas al canal.

  1. Tenga un administrador de organización que cree una clave API segura limitada a la aplicación de previsualización y seleccione App PreviewConsulte Claves API.
  2. Utilice un canal único y no público como pr-123. No pasar --default, --self-assign, opciones de lanzamiento, o --delete-linked-bundle-on-upload.
  3. Subir y promocionar el paquete de PR en una sola orden, luego eliminar el canal y el paquete propiedad cuando se cierre el PR:
Ventana de terminal
APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"


npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"


npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel crea un canal faltante, sube el paquete y lo promociona en un flujo. La limpieza es atómica y verificada por propiedad: la clave puede eliminar solo un canal que creó y su paquete vinculado, no compartido. No puede cambiar, promocionar o eliminar un canal principal/por defecto existente, un canal de otro teclado de vista previa o un paquete de otra clave.

If reviewers need a QR code or preview URL, an administrator must enable previews once for the app:

Ventana de terminal
npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

Un clave de vista de la aplicación no puede habilitar vistas por sí sola porque no tiene permiso para configuraciones de la aplicación. En GitHub Acciones, ejecuta trabajos de vista previa que contienen secretos en pull_request, no pull_request_target, y restringe a PRs de la misma repositorio con github.event.pull_request.head.repo.full_name == github.repository.

Desplegando a un Dispositivo

Sección titulada “Desplegando a un Dispositivo”

Ahora que entiendes los canales, estás listo para empezar a desplegar actualizaciones en vivo a dispositivos reales. El proceso básico es:

  1. Instala el Capgo SDK en tu aplicación
  2. Configura la aplicación para escuchar tu canal deseado
  3. Carga una compilación y asigna a ese canal
  4. Lanza la aplicación y espera a que se actualice!

Para una guía detallada, consulta el Actualizaciones en Vivo manual. ¡Feliz actualizando!

Uso Avanzado de Canales: Segmentación de Usuarios

Sección titulada “Uso Avanzado de Canales: Segmentación de Usuarios”

Los canales pueden usarse para más que solo etapas de desarrollo. Son una herramienta poderosa para la segmentación de usuarios, permitiendo características como:

  • Feature flags for different user tiers
  • Pruebas A/B
  • Implementación gradual de características
  • Programas de pruebas beta

Aprende a implementar estos casos de uso avanzados en nuestra guía: Cómo segmentar a los usuarios por plan y canales para banderas de características y pruebas A/B.

Sigue adelante desde los canales

Mantén el progreso desde los canales

Si estás utilizando Channels para planificar la ruta de los canales y la implementación gradual, conecta con Canales para los detalles de implementación en Canales, Canales para los detalles de implementación en Canales, Solución de Pruebas Beta para el flujo de trabajo del producto en Solución de Pruebas Beta, Solución de Enfoque de Versión para el flujo de trabajo del producto en Solución de Enfoque de Versión, y Capgo Mejores Prácticas de Entorno: Etapa con un ID de Aplicación Móvil para el contexto práctico en Capgo Mejores Prácticas de Entorno: Etapa con un ID de Aplicación Móvil.