通道

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

Channels 是 Capgo 管理应用更新的核心机制。通过它们，你可以控制用户接收更新的方式和时机，从而实现 A/B 测试、分阶段发布以及针对特定平台的更新等功能。

了解 Channels

Channel 代表了应用更新的分发轨道。每个 Channel 都可以配置特定的规则和限制：

Bundle 版本控制：指定用户接收哪个 bundle (版本)
平台定向：针对特定平台 (iOS/Android/Electron)
更新策略：控制更新的推送方式
设备限制: 管理哪些设备可以获取更新

Channel 配置选项

public: 设置为新设备的默认 channel。
在 Native Build 下禁用自动更新: 当设备的 Native Build 版本高于 channel 的 stable bundle 时，阻止更新。
禁用自动更新: 控制更新行为 (major, minor, patch, version_number，或 none). metadata 被视为以下内容的别名： version_number.
updatePackage：控制设备下载 zip、delta 还是两者都下载 (all, zip, delta, zip_from_builtin，或 delta_from_builtin）。参见下载格式.
ios/android/electron：启用或禁用按平台分发。
允许设备自行设置：允许设备自行选择 channel。
允许模拟器, 允许设备, 允许开发人员, 允许生产环境: 控制哪些设备和 build 类型接收更新。
渐进式发布: 在向特定用户群推送目标 bundle 的同时，保持主 bundle 的稳定性。详见渐进式发布.

最佳实践

测试通道: 维护用于内部验证的测试 channel
分阶段发布: 使用多个 channel 进行渐进式更新部署
平台隔离根据需要为 iOS、Android 和 Electron 创建独立的 channel
Bundle 版本控制：使用语义化版本让更新路径更清晰

端点

POST

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

创建或更新 Channel 配置。

请求体

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
}

对于 rollout 和 auto-pause 字段，API 也接受等效的 snake_case 形式，例如 rollout_version 或 auto_pause_enabled. updatePackage 也接受 update_package。如果两种形式都提供，则以 camelCase 值为准。 rollback 仅支持 camelCase。

rollout target 需要已有 channel。它必须已分配稳定 bundle，或通过 version 在同一个 POST 请求中接收。 rollback 以及 promoteToStable 是终止操作；请勿将它们组合使用。

请求示例

为现有 channel 配置 5% 的渐进式发布： production 该 channel 的稳定版 bundle 已设置：

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

POST 是 upsert 操作，仅返回状态。请发起 GET 请求读取生成的 channel 配置。

App Preview 密钥边界

要为 PR preview 实现最小权限，请使用以下方式认证此 endpoint： authorization: $CAPGO_API_KEY 或 capgkey: $CAPGO_API_KEY。该 x-api-key Channels API 不接受 header。

一次 app_preview key 可以创建一个新的非公开预览 channel。创建时会自动为该 key 分配仅限该 channel 的 channel-scoped lifecycle binding。该角色不包含 channel.update_settings，因此无法使用 POST 来更新现有的 channel，包括现有的 default 或 main channel。

留空 public 或将其设置为 false) 用于 PR 预览 channel。请使用 bundle upload --channel 进行创建和 upload 流程，而不是将 POST 视为通用的预览 channel upsert。

GET

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

获取 channel 信息。每页返回 50 个 channel。如果不 channel，响应是一个数组。使用 channel，响应是一个 channel 对象。

查询参数

app_id：必填。您的应用 ID
page：选填。用于分页的页码
channel：选填。要获取的指定 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 是一个仅限输入的快捷方式，不会被返回。暂停中的 rollout 会以非空值表示 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/

删除 channel。请注意，这将影响所有使用该 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"
}

App Preview 清理

使用 delete_bundle: true，一个 app_preview 该 key 只能原子性地清理其创建的 channel 及其关联的未共享 bundle。该 key 不会获得通用 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/

错误处理

所有错误均采用以下文档中描述的标准错误格式： API 概览.

常见的错误场景及其响应：

// 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": {}
}

常见用例

Beta 测试

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

生产环境发布

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

特定平台的更新

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

继续探索 Channels

如果你正在使用通道要规划 Channel 路由和分阶段发布，请将其与通道有关 Channels 的实现细节，通道有关 Channels 的实现细节， Beta 测试解决方案有关 Beta 测试解决方案的产品工作流，版本定向解决方案有关版本定向解决方案的产品工作流，以及 Capgo 环境最佳实践：使用一个 Mobile App ID 进行 Staging 有关 Capgo 环境最佳实践：使用一个 Mobile App ID 进行 Staging 的实际场景。