チャンネル

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

Capgo において、Channel はアプリのアップデートを管理するための核となる仕組みです。ユーザーへのアップデート配信方法やタイミングを制御できるため、A/B テストや段階的なロールアウト、プラットフォームごとのアップデートといった機能を実現できます。

チャンネルの仕組み

Channel は、アプリのアップデートを配信するためのトラックを表します。各 Channel には、以下のような特定のルールや制約を設定できます：

Bundle（バージョン）の制御：ユーザーが受け取る bundle（バージョン）を指定
プラットフォームのターゲット指定：特定のプラットフォーム（iOS/Android/Electron）を対象にする
アップデートポリシー：アップデートの配信方法を制御
デバイスの制限: アップデートにアクセスできるデバイスを管理します

チャネル設定オプション

公開: 新規デバイスのデフォルトチャネルとして設定します。
disableAutoUpdateUnderNative: デバイスのネイティブアプリのバージョンがチャネルのstable bundleより新しい場合、アップデートを防止します。
disableAutoUpdate: アップデートの挙動を制御します（major, minor, patch, version_number、または none). metadata は〜のエイリアスとして受け付けられます version_number.
updatePackage: デバイスがzip、delta、またはその両方をダウンロードするかどうかを制御します（all, zip, delta, zip_from_builtin、または delta_from_builtin）。参照: ダウンロード形式.
ios/android/electron: プラットフォームごとに配信の有効/無効を切り替えます。
device_self_set_allowance: デバイスがチャンネルを選択できるようにします。
emulator_allow, デバイスを許可, 開発を許可する, 本番環境を許可: 更新を受け取るデバイスやビルドタイプを制御します。
段階的ロールアウト: 特定のユーザー層（sticky cohort）にターゲットとなるbundleを公開しつつ、安定したbundleを維持します。詳細は段階的なロールアウト.

ベストプラクティス

Testing Channel を参照してください: 社内検証用のテスト用チャンネルを維持します
段階的なロールアウト: 複数のチャンネルを使用して、段階的にアップデートをデプロイします
プラットフォームの分離: 必要に応じて iOS、Android、Electron 用に個別のチャンネルを作成します
Bundle (バージョン) 管理: 使用するセマンティックバージョニング明確なアップデートパスのために

エンドポイント

POST

https://api.capgo.app/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 ターゲットには既存の channel が必要です。すでに stable な bundle が割り当てられているか、以下を通じて割り当てる必要があります： version を同じ POST リクエスト内で指定してください。 rollback と promoteToStable は最終的なアクションです。これらを組み合わせて使用しないでください。

リクエスト例

既存のチャネルに5%のロールアウトを設定します production （安定版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リクエストを送信してください。

App Previewのキー境界

最小権限のPRプレビューには、このエンドポイントを次で認証してください: authorization: $CAPGO_API_KEY または capgkey: $CAPGO_API_KEY。 x-api-key Channels API は header を受け付けません。

一つの app_preview key は新しい非公開のプレビューチャンネルを作成できます。作成時に、その key にはそのチャンネル専用のチャンネルスコープの lifecycle binding が自動的に付与されます。このロールには次が含まれません： channel.update_settingsそのため、POST を使って既存のチャンネル（既存の default や main チャンネルを含む）を更新することはできません。

退出 public 未設定にする（または次の値に設定する： false）を PR プレビューチャンネルに設定します。使用するには bundle upload --channel 作成と upload のフローには、POST を汎用的なプレビューチャンネルの upsert として扱うのではなく、こちらを使用してください。

GET

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

チャンネル情報を取得します。1ページあたり50件のチャンネルを返します。指定しない場合 channel、レスポンスは配列です。また、 channel、レスポンスは1つの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 は入力専用のショートカットであり、返されません。一時停止中のロールアウトは、null 以外の値で表されます。 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"
}

App Previewのクリーンアップ

を使用すると、 delete_bundle: true、つまり app_preview keyは、自身が作成したチャンネルと、それに紐付く共有されていない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": {}
}

よくあるユースケース

ベータテスト

{
  "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の続きへ

使用している場合 チャンネル チャンネルルーティングと段階的ロールアウトを計画するには、次と組み合わせてください：チャンネル Channelsの実装の詳細については、チャンネル Channelsの実装の詳細については、ベータテストソリューション Beta Testing Solution のプロダクトワークフロー向け、バージョンターゲティングソリューション Version Targeting Solution のプロダクトワークフロー向け、および Capgo 環境のベストプラクティス：1つのモバイルアプリIDでステージング実践的な内容については、Capgo の環境ベストプラクティス「単一の Mobile App ID でのステージング」を参照してください。