Canales

Los Channels son el mecanismo central para gestionar las actualizaciones de tu app en Capgo. Te permiten controlar cómo y cuándo tus usuarios reciben actualizaciones, lo que habilita funciones como A/B testing, rollouts escalonados y actualizaciones específicas por plataforma.

Entender los Channels

Un channel representa una vía de distribución para las actualizaciones de tu app. Cada channel puede configurarse con reglas y restricciones específicas:

• Control de bundle (versión): Especifica qué bundle (versión) reciben los usuarios
• Segmentación por plataforma: Apunta a plataformas específicas (iOS/Android/Electron)
• Políticas de actualización: Controla cómo se entregan las actualizaciones
• Restricciones de dispositivo: Manage which devices can access updates

Opciones de configuración del canal

• público: Establecer como canal por defecto para nuevos dispositivos.
• disableAutoUpdateUnderNative: Evita actualizaciones si la versión nativa del dispositivo es más reciente que el bundle estable del canal.
• disableAutoUpdate: Controla el comportamiento de las actualizaciones (major, minor, patch, version_number, o none). metadata se acepta como alias de version_number.
• updatePackage: Controla si los dispositivos descargan un zip, un delta o ambos (all, zip, delta, zip_from_builtin, o delta_from_builtin). Consulta Formato de descarga.
• ios/android/electron: Activa o desactiva la entrega por plataforma.
• permitir_autoconfiguración_dispositivo: Deja que los dispositivos elijan su canal.
• permitir_emulador, permitir_dispositivo, permitir_dev, permitir_prod: Controla qué dispositivos y tipos de build reciben actualizaciones.
• sección de Rollout progresivo: Mantén un bundle estable mientras expones un bundle específico a un grupo cautivo. Ver Despliegues progresivos.

Buenas prácticas

1. Probando el canal: Mantén un canal de pruebas para validación interna
2. Despliegue gradual: Usa múltiples canales para un despliegue gradual de actualizaciones
3. Separación de Plataformas: Crea canales separados para iOS, Android y Electron cuando sea necesario
4. Control de bundle (versión): Usa versionado semántico para rutas de actualización claras

Endpoints

POST

https://api.capgo.app/channel/

Crea o actualiza la configuración de un canal.

Cuerpo de la solicitud

type DisableAutoUpdate = "major" | "minor" | "patch" | "version_number" | "metadata" | "none"
type AutoPauseAction = "pause" | "rollback" | "notify"

interface ChannelSet {
  app_id: string
  channel: string
  version?: string | null // stable bundle name
  public?: boolean
  disableAutoUpdateUnderNative?: boolean
  disableAutoUpdate?: DisableAutoUpdate
  updatePackage?: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  ios?: boolean
  android?: boolean
  electron?: boolean
  allow_device_self_set?: boolean
  allow_emulator?: boolean
  allow_device?: boolean
  allow_dev?: boolean
  allow_prod?: boolean

  // Progressive rollout (camelCase is preferred)
  rolloutVersion?: string | number | null // target bundle name or ID
  rolloutPercentage?: number // 0–100
  rolloutPercentageBps?: number // 0–10000; takes precedence when both are set
  rolloutEnabled?: boolean
  rolloutPaused?: boolean // input-only convenience flag
  rolloutPausedAt?: string | null // ISO timestamp or null
  rolloutPauseReason?: string | null
  rolloutCacheTtlSeconds?: number // 60–31536000
  rollback?: boolean
  promoteToStable?: boolean

  // Rollout auto-pause policy
  autoPauseEnabled?: boolean
  autoPauseWindowMinutes?: number
  autoPauseFailureRateBps?: number | null
  autoPauseConfidence?: number
  autoPauseMinAttempts?: number | null
  autoPauseMinFailures?: number | null
  autoPauseAction?: AutoPauseAction
  autoPauseCooldownMinutes?: number
}

Para los campos de rollout y auto-pause, API también acepta el formato snake_case equivalente, como por ejemplo: rollout_version o auto_pause_enabled. updatePackage también acepta update_package. Si se proporcionan ambos formatos, el valor en camelCase tiene prioridad. rollback es únicamente en camelCase.

Un objetivo de rollout requiere un canal existente. Debe tener un bundle estable asignado o recibir uno mediante version en la misma solicitud POST. rollback y promoteToStable son acciones terminales; no las combines entre sí.

Ejemplo de solicitud

Configura un rollout del 5% para un production channel cuyo bundle estable ya está definido:

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "production",
    "rolloutVersion": "1.3.0",
    "rolloutPercentage": 5,
    "rolloutEnabled": true,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseMinAttempts": 100,
    "autoPauseAction": "pause"
  }' \
  https://api.capgo.app/channel/

Respuesta exitosa

{
  "status": "ok"
}

POST funciona como un upsert y solo devuelve su estado. Haz un GET para leer la configuración del channel resultante.

Límite de la clave de App Preview

Para un PR preview con privilegios mínimos, autentica este endpoint con authorization: $CAPGO_API_KEY o capgkey: $CAPGO_API_KEY. El x-api-key Channels API no acepta el header.

Una app_preview key puede crear un nuevo canal de preview no público. Al crearlo, esa key recibe automáticamente un lifecycle binding limitado a ese canal. El rol no incluye channel.update_settings, por lo que no puede usar POST para actualizar un canal existente, incluido un canal default o main existente.

Deja public sin definir (o ponlo en false) para canales de preview de PR. Usa bundle upload --channel para el flujo de creación y upload, en lugar de tratar el POST como un upsert general de preview-channel.

GET

https://api.capgo.app/channel/

Obtener información del canal. Devuelve 50 canales por página. Sin channel, la respuesta es un array. Con channel, la respuesta es un objeto de canal.

Parámetros de consulta

• app_id: Requerido. El ID de tu app
• page: Opcional. Número de página para la paginación
• channel: Opcional. Nombre del canal específico a recuperar

Solicitudes de ejemplo

# Get all channels
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app"

# Get a specific channel
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&channel=production"

# Get the next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&page=1"

Tipo de respuesta

interface Channel {
  id: number
  created_at: string
  updated_at: string
  name: string
  app_id: string
  created_by: string
  public: boolean
  disableAutoUpdateUnderNative: boolean
  disableAutoUpdate: DisableAutoUpdate
  updatePackage: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  allow_device_self_set: boolean
  allow_emulator: boolean
  allow_device: boolean
  allow_dev: boolean
  allow_prod: boolean
  version: { id: number, name: string } | null // stable bundle

  // These three response identifiers intentionally use snake_case.
  rollout_version: number | null
  rollout_id: string
  rollout_version_info: { id: number, name: string } | null

  rolloutPercentageBps: number
  rolloutEnabled: boolean
  rolloutPausedAt: string | null
  rolloutPauseReason: string | null
  rolloutCacheTtlSeconds: number
  autoPauseEnabled: boolean
  autoPauseWindowMinutes: number
  autoPauseFailureRateBps: number | null
  autoPauseConfidence: number
  autoPauseMinAttempts: number | null
  autoPauseMinFailures: number | null
  autoPauseAction: AutoPauseAction
  autoPauseCooldownMinutes: number
  autoPauseLastTriggeredAt: string | null
  autoPauseLastCheckedAt: string | null
}

rolloutPaused es un acceso directo de solo entrada y no se devuelve. Un rollout pausado se representa con un valor no nulo rolloutPausedAt.

Ejemplo de respuesta

[
  {
    "id": 1,
    "name": "production",
    "app_id": "com.example.app",
    "updatePackage": "all",
    "version": { "id": 1, "name": "1.2.0" },
    "rollout_version": 2,
    "rollout_id": "e60c19c9-2e65-4e0d-bc06-d1f5b4f96276",
    "rollout_version_info": { "id": 2, "name": "1.3.0" },
    "rolloutPercentageBps": 500,
    "rolloutEnabled": true,
    "rolloutPausedAt": null,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseAction": "pause"
  }
]

ELIMINAR

https://api.capgo.app/channel/

Elimina un canal. Ten en cuenta que esto afectará a todos los dispositivos que usen este canal.

Cuerpo de la solicitud

interface Channel {
  channel: string
  app_id: string
  delete_bundle?: boolean // also delete the linked bundle
}

Ejemplo de solicitud

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "com.example.app",
    "channel": "beta"
  }' \
  https://api.capgo.app/channel/

Respuesta exitosa

{
  "status": "ok"
}

Limpieza de App Preview

Con delete_bundle: true, una app_preview la key puede limpiar de forma atómica solo un canal que haya creado y su bundle vinculado y no compartido. La key no recibe bundle.delete permiso.

curl -X DELETE \
  -H "capgkey: $CAPGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "pr-123",
    "delete_bundle": true
  }' \
  https://api.capgo.app/channel/

Manejo de errores

Todos los errores utilizan el formato estándar descrito en la visión general de API.

Escenarios de error comunes y sus respuestas:

// The API key has no access to the app
{
  "error": "cannot_access_app",
  "message": "You can't access this app",
  "moreInfo": { "app_id": "com.example.app" }
}

// Invalid disableAutoUpdate value
{
  "error": "invalid_disable_auto_update",
  "message": "Disable auto update must be major, minor, patch, version_number, metadata, or none",
  "moreInfo": { "disableAutoUpdate": "always" }
}

// Rollout percentage out of range
{
  "error": "invalid_rollout_percentage",
  "message": "Rollout percentage must be between 0 and 100",
  "moreInfo": { "rolloutPercentage": 150 }
}

// DELETE without a channel name
{
  "error": "missing_channel_name",
  "message": "You must provide a channel name",
  "moreInfo": {}
}

Casos de uso comunes

1. Pruebas beta

{
  "app_id": "com.example.app",
  "channel": "beta",
  "version": "1.2.0-beta",
  "public": false,
  "allow_emulator": true,
  "allow_dev": true
}

2. Despliegue en Producción

{
  "app_id": "com.example.app",
  "channel": "production",
  "version": "1.2.0",
  "public": true,
  "disableAutoUpdate": "minor"
}

3. Updates por Plataforma

{
  "app_id": "com.example.app",
  "channel": "ios-hotfix",
  "version": "1.2.1",
  "ios": true,
  "android": false
}

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.