앱 업데이트 채널 관리 가이드

채널

Capgo의 핵심 업데이트 관리 메커니즘인 채널입니다. 사용자가 업데이트를 받는 방법과 시기를 제어할 수 있으며 A/B 테스트, 단계별 롤아웃 및 플랫폼별 업데이트와 같은 기능을 활성화할 수 있습니다.

채널은 앱 업데이트의 배포 트랙을 나타냅니다. 각 채널은 특정 규칙과 제약을 구성할 수 있습니다:

  • 버nd (버전) 제어: 사용자가 받는 버nd (버전) 지정
  • 플랫폼 목표 설정: iOS/Android/Electron 플랫폼을 대상으로 설정합니다.
  • 업데이트 정책: 업데이트 전달 방법을 제어합니다.
  • 장치 제한: 업데이트에 접근할 수 있는 장치를 관리합니다.

채널 구성 옵션

채널 구성 옵션
  • 공개: 새로운 장치에 대한 기본 채널을 설정합니다.
  • 네이티브 앱 버전보다 최신인 채널의 안정적인 패키지를 받지 않도록 업데이트를 방지합니다.disableAutoUpdateUnderNative
  • 업데이트 자동화 끄기: 업데이트 동작 제어 (major, minor, metadata, patch, 또는 none).
  • 업데이트 패키지: 장치가 zip, delta, 또는 둘 다 다운로드할지 결정하는지 여부 (all, zip, delta, zip_from_builtin, 또는 delta_from_builtin). 자세히 보기 업데이트 패키지.
  • ios/android/electron: 플랫폼별로 전달을 허용하거나 차단합니다.
  • 장치 자체가 채널을 선택할 수 있도록 허용합니다.: Let devices choose their channel.
  • allow_emulator, allow_device, allow_dev, allow_prod: 장치 및 빌드 유형에 업데이트를 받도록 제어합니다.
  • 진보적 롤아웃: 안정적인 번들을 유지하면서 특정 그룹에 특정 번들을 노출합니다. 진보적 롤아웃.

Best Practices

Best Practices
  1. 테스트 채널: 내부 검증을 위한 테스트 채널 유지
  2. 차단된 출시: 여러 채널을 사용하여 점진적인 업데이트 배포
  3. 플랫폼 분리: iOS, Android 및 Electron에 필요한 경우 별도의 채널을 생성
  4. 버전 제어 (Bundle): 세미나 버전 명확한 업데이트 경로를 위해

엔드포인트

엔드포인트 섹션

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
}

rollout 및 자동 중단 필드의 경우 API도 해당하는 snake_case 형식, 예를 들어 rollout_version 또는 auto_pause_enabled. updatePackage 또한接受 update_package. 양쪽 형식이 제공된 경우 camelCase 값이 우선합니다. rollback camelCase 형식만 허용됩니다.

롤아웃 대상은 기존 채널이 필요합니다. 안정적인 번들을 할당하거나 POST 요청과 함께 할당받아야 합니다. version in the same POST request. 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"
}

업데이트

앱 미리보기 키 경계

앱 미리보기 키 경계 섹션

최소 권한의 PR 미리보기에 대해 이 엔드포인트를 인증해야 합니다. authorization: $CAPGO_API_KEY 또는 capgkey: $CAPGO_API_KEYChannels __CAPGO_KEEP_0__의 헤더는 수락되지 않습니다. x-api-key header is not accepted by the Channels API.

이러한 채널을 업데이트하기 위해 POST를 사용할 수 없습니다. app_preview 미리보기 채널의 경우 PR 미리보기 채널을 설정하지 않거나 channel.update_settings를 설정하세요.

업데이트를 사용할 수 없습니다. public 업데이트를 사용할 수 없습니다. false업데이트를 사용할 수 없습니다. bundle upload --channel 생성 및 업로드 흐름을 위해 POST를 일반적인 미리보기 채널 업데이트로 다루지 않습니다.

GET

GET

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

채널 정보를 가져옵니다. 50개의 채널이 한 페이지에 반환됩니다. channel,이 경우 응답은 배열입니다. channel,이 경우 응답은 하나의 채널 객체입니다.

  • app_id: 필수. 앱의 ID
  • page: 선택적. 페이지 번호를 위한 페이징
  • channel: 선택적. 특정 채널 이름을 가져오기 위해

Example Requests

예시 요청 섹션
터미널 창
# 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"
}

앱 미리보기 정리

앱 미리보기 정리

그리고 delete_bundle: true, app_preview 키는 bundle.delete 만들어진 채널과 연결된, 공유되지 않은 번들을 atomically 정리할 수 있습니다. 키는 일반

권한을 받지 않습니다.
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. Beta Testing
{
"app_id": "com.example.app",
"channel": "beta",
"version": "1.2.0-beta",
"public": false,
"allow_emulator": true,
"allow_dev": true
}
  1. Production Rollout
{
"app_id": "com.example.app",
"channel": "production",
"version": "1.2.0",
"public": true,
"disableAutoUpdate": "minor"
}
  1. Platform-Specific Updates
{
"app_id": "com.example.app",
"channel": "ios-hotfix",
"version": "1.2.1",
"ios": true,
"android": false
}

If you are using Channels to plan channel routing and staged rollout, connect it with 채널 채널 채널 베타 테스트 솔루션 채널 버전 대상 솔루션 채널 __CAPGO_KEEP_0__ 환경 최적화: 단일 모바일 앱 ID로 스테이징 Capgo Environment Best Practices: Staging with One Mobile App ID for the practical context in Capgo Environment Best Practices: Staging with One Mobile App ID.