채널

Capgo에서 Channels는 앱 업데이트를 관리하는 핵심 메커니즘입니다. Channels를 통해 사용자가 업데이트를 받는 방식과 시점을 제어할 수 있으며, A/B 테스트, 단계적 배포(staged rollouts), 플랫폼별 업데이트와 같은 기능을 구현할 수 있습니다.

채널 이해하기

Channel은 앱 업데이트를 배포하는 트랙을 의미합니다. 각 Channel은 다음과 같은 특정 규칙과 제약 사항을 설정할 수 있습니다:

• Bundle(버전) 관리: 사용자가 받을 bundle(버전) 지정
• 플랫폼 타겟팅: 특정 플랫폼(iOS/Android/Electron) 타겟팅
• 업데이트 정책: 업데이트 전달 방식 제어
• 기기 제한 사항: 업데이트에 접근할 수 있는 디바이스를 관리합니다.

채널 구성 옵션

• public: 새 디바이스의 기본 채널로 설정합니다.
• disableAutoUpdateUnderNative: 디바이스의 네이티브 앱 버전이 채널의 stable bundle보다 최신이면 업데이트를 방지합니다.
• disableAutoUpdate: 업데이트 동작을 제어합니다 (major, minor, patch, version_number, 또는 none). metadata 의 alias로 허용됨 version_number.
• updatePackage: 디바이스가 zip, delta 또는 둘 다를 다운로드할지 여부를 제어합니다 (all, zip, delta, zip_from_builtin, 또는 delta_from_builtin"). 규칙은 다운로드 형식.
• ios/android/electron): 플랫폼별 배포 여부를 설정합니다.
• device_self_set_allow: 디바이스가 직접 채널을 선택할 수 있도록 합니다.
• emulator_허용, 기기 허용, 개발자 허용, allow_prod: 업데이트를 받을 디바이스 및 빌드 타입을 제어합니다.
• 점진적 롤아웃: 안정적인 번들을 유지하면서 스티키 코호트에 타겟 번들을 노출합니다. 참고 단계적 배포.

모범 사례

1. 테스트 채널: 내부 검증을 위한 테스트 채널을 운영합니다.
2. 단계적 배포: 여러 채널을 사용하여 업데이트를 점진적으로 배포합니다.
3. 플랫폼 분리: 필요에 따라 iOS, Android, Electron용 채널을 각각 생성합니다.
4. 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 대상은 기존 채널이 필요합니다. 이미 할당된 안정적인 bundle이 있거나 다음을 통해 받아야 합니다 version 같은 POST 요청에서. rollback 및 promoteToStable 는 최종 작업입니다. 서로 조합하여 사용하지 마세요.

요청 예시

이미 안정적인 번들이 설정된 기존 production 채널에 대해 5% 롤아웃을 구성합니다:

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에서 허용되지 않습니다.

한 app_preview 키는 새 비공개 프리뷰 채널을 생성할 수 있습니다. 생성 시 해당 키에는 해당 채널에만 적용되는 채널 범위 lifecycle binding이 자동으로 부여됩니다. 이 역할에는 channel.update_settings 권한이 포함되지 않으므로, 기존 default 또는 main 채널을 포함한 기존 채널을 POST로 업데이트할 수 없습니다.

다음 값은 public unset 상태로 두거나 값을 지정하세요 false. PR 프리뷰 채널의 경우 bundle upload --channel POST를 일반적인 preview-channel upsert로 처리하는 대신, 생성 및 upload 흐름에 사용합니다.

GET

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

채널 정보를 가져옵니다. 페이지당 50개 채널을 반환합니다. 없이 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 입력 전용 단축키이며 반환되지 않습니다. 일시 중지된 롤아웃은 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"
  }
]

DELETE

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 키는 자신이 생성한 채널과 그에 연결된, 공유되지 않은 bundle만 원자적으로 정리할 수 있습니다. 이 키는 일반적인 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": {}
}

주요 사용 사례

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의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing Solution의 제품 워크플로우를 위해, 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우를 위해, 그리고 Capgo 환경 베스트 프랙티스: 하나의 Mobile App ID로 스테이징하기 Capgo Environment Best Practices: Staging with One Mobile App ID의 실무 컨텍스트를 위해.