频道

频道是 Capgo 中应用程序更新管理的核心机制。它们允许您控制用户何时接收更新，并启用 A/B 测试、分阶段发布和平台特定更新等功能。

了解频道

频道代表应用程序更新的分发轨迹。每个频道都可以配置特定的规则和约束:

• 包（版本）控制: 指定用户接收的包（版本）
• 平台目标: 为 iOS/Android/Electron 平台设置目标
• 更新策略: 控制更新的分发方式
• 设备限制: 管理可以访问更新的设备

频道配置选项

• 公共: 设为新设备的默认频道
• 禁用原生应用更新: 当设备的原生应用版本新于频道的稳定包时，防止更新
• disableAutoUpdate: 控制更新行为 (major, minor, metadata, patch, 或 none).
• updatePackage: 控制设备下载 zip、delta 或两者 (all, zip, delta, zip_from_builtin, 或 delta_from_builtin). 请参见 更新包.
• ios/android/electron: 根据平台启用或禁用分发.
• allow_device_self_set: 允许设备选择频道.
• 允许模拟器, 允许设备, 允许开发, 允许生产: 控制哪些设备和构建类型接收更新。
• 渐进式发布: 保持稳定的捆绑包，同时将目标捆绑包暴露给粘性群体。请参见 渐进式发布.

最佳实践

1. 测试频道: 为内部验证保留一个测试频道
2. 阶段性发布: 使用多个渠道进行渐进式更新部署
3. 平台分离: 根据需要创建 iOS、Android 和 Electron 的独立渠道
4. 包（版本）控制: 使用 语义化版本 以清晰的更新路径

API

POST

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

创建或更新一个频道配置。

请求体

type DisableAutoUpdate = "major" | "minor" | "metadata" | "patch" | "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
}

对于滚动和自动暂停字段，API 也接受等效的 snake_case 形式，如 rollout_version 或 auto_pause_enabled. updatePackage 也接受 update_package. 如果同时提供两种形式，驼峰式值将获胜。 rollback 仅支持驼峰式。

一个滚动目标需要一个现有的频道。它必须有一个稳定的捆绑包已经分配或通过 version 在同一个POST请求中接收。 rollback 并且 promoteToStable 终端操作；请勿将它们合并

示例请求

配置一个已有的5%的滚动频率的频道，其稳定包已经设置: production 终端窗口

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/

成功响应

{
  "status": "ok"
}

示例请求

App Preview key boundary

为最小权限的PR预览而进行身份验证 authorization: $CAPGO_API_KEY 或 capgkey: $CAPGO_API_KEY为最小权限的PR预览而进行身份验证 x-api-key header is not accepted by the Channels API.

为最小权限的PR预览而进行身份验证 app_preview 或 channel.update_settings或

标题栏不被Channels __CAPGO_KEEP_0__接受 public 一个 false可以创建一个新的非公共预览频道。创建自动为该频道分配一个通道范围的生命周期绑定。该角色不包括，因此无法使用POST更新现有频道，包括现有默认频道或主频道。 bundle upload --channel 为创建和上传流程而不是将 POST 视为一般预览频道 upsert。

GET

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

获取频道信息。每页返回 50 个频道。没有 channel,响应为数组。有 channel,响应为一个频道对象。

查询参数

• app_id:必填。您的应用程序 ID
• page:可选。分页的页数
• channel:可选。要检索的特定频道名称

示例请求

# 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"

响应类型

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 是一个只读输入快捷方式，暂停的发布将用非空值表示 rolloutPausedAt.

示例响应

[
  {
    "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"
  }
]

删除

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

删除一个频道。注意，这将影响所有使用此频道的设备。

请求体

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

示例请求

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/

成功响应

{
  "status": "ok"
}

应用预览清理

有一个 delete_bundle: true可以原子性地清理它创建的频道及其链接但未共享的包。 app_preview 该密钥不获得一般 bundle.delete 权限。

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/

错误处理

常见错误场景及其响应：

// Channel not found
{
  "error": "Channel not found",
  "status": "KO"
}

// Invalid bundle (version) format
{
  "error": "Invalid version format. Use semantic versioning",
  "status": "KO"
}

// Invalid update policy
{
  "error": "Invalid disableAutoUpdate value",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage channels",
  "status": "KO"
}

常见用例

1. 测试版

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

2. 发布

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

3. 平台特定更新

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

继续从 Channels

Channels 继续从 Channels 以规划通道路由和阶段发布，连接它与 频道 频道 频道 测试版体验解决方案 测试版体验解决方案 版本定位解决方案 版本定位解决方案 __CAPGO_KEEP_0__ 环境最佳实践：同一移动应用ID的分期 Capgo 环境最佳实践：同一移动应用ID的分期 for the practical context in Capgo Environment Best Practices: Staging with One Mobile App ID.