Channel

Channels adalah mekanisme inti untuk mengelola pembaruan aplikasi di Capgo. Channel memungkinkan Anda mengontrol cara dan waktu pengguna menerima pembaruan, sehingga mendukung fitur seperti A/B testing, staged rollouts, dan pembaruan spesifik platform.

Memahami Channels

Channel mewakili jalur distribusi untuk pembaruan aplikasi Anda. Setiap channel dapat dikonfigurasi dengan aturan dan batasan tertentu:

• Kontrol Bundle (versi): Menentukan bundle (versi) yang diterima pengguna
• Target Platform: Menargetkan platform tertentu (iOS/Android/Electron)
• Kebijakan Pembaruan: Mengontrol cara pembaruan dikirim
• Batasan Perangkat: Kelola perangkat mana yang dapat mengakses update

Opsi Konfigurasi Channel

• public: Atur sebagai channel default untuk perangkat baru.
• disableAutoUpdateUnderNative: Cegah update jika versi native app perangkat lebih baru dari stable bundle channel.
• disableAutoUpdate: Kontrol perilaku update (major, minor, patch, version_number, atau none). metadata diterima sebagai alias dari version_number.
• updatePackage: Mengontrol apakah perangkat mengunduh zip, delta, atau keduanya (all, zip, delta, zip_from_builtin, atau delta_from_builtin). Lihat Format download.
• ios/android/electron: Aktifkan atau nonaktifkan pengiriman berdasarkan platform.
• allow_device_self_set: Membiarkan perangkat memilih channel mereka.
• allow_emulator, allow_device, allow_dev, allow_prod: Mengontrol jenis perangkat dan build mana yang menerima update.
• Rollout bertahap: Menjaga bundle stabil sambil mengekspos bundle target ke kohort sticky. Lihat Rollout bertahap.

Praktik Terbaik

1. Channel Pengujian: Memelihara testing channel untuk validasi internal
2. Staged Rollout: Menggunakan beberapa channel untuk deployment update bertahap
3. Pemisahan Platform: Buat channel terpisah untuk iOS, Android, dan Electron jika diperlukan
4. Kontrol Bundle (versi): Gunakan semantic versioning untuk jalur update yang jelas

Endpoint

POST

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

Buat atau perbarui konfigurasi channel.

Body Request

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
}

Untuk field rollout dan auto-pause, API juga menerima format snake_case yang setara, seperti rollout_version atau auto_pause_enabled. updatePackage juga menerima update_package. Jika kedua format diberikan, nilai camelCase yang berlaku. rollback hanya menggunakan camelCase.

Target rollout memerlukan channel yang sudah ada. Channel tersebut harus sudah memiliki bundle stabil atau menerimanya melalui version dalam request POST yang sama. rollback dan promoteToStable adalah aksi terminal; jangan menggabungkannya satu sama lain.

Contoh Request

Konfigurasi rollout 5% untuk production channel yang sudah ada dengan stable bundle yang sudah di-set:

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/

Respons Sukses

{
  "status": "ok"
}

POST bersifat upsert dan hanya mengembalikan status. Lakukan request GET untuk membaca konfigurasi channel yang dihasilkan.

Batas key App Preview

Untuk PR preview dengan hak akses minimum, autentikasi endpoint ini dengan authorization: $CAPGO_API_KEY atau capgkey: $CAPGO_API_KEY. x-api-key Header tidak diterima oleh Channels API.

Sebuah app_preview key dapat membuat channel preview non-publik baru. Pembuatan otomatis memberi key tersebut binding lifecycle dengan scope channel, hanya untuk channel itu. Role ini tidak mencakup channel.update_settings, sehingga tidak bisa menggunakan POST untuk memperbarui channel yang sudah ada, termasuk channel default atau main yang sudah ada.

Biarkan public tidak diatur (atau set ke false) untuk channel preview PR. Gunakan bundle upload --channel untuk alur pembuatan dan upload alih-alih memperlakukan POST sebagai upsert channel preview umum.

GET

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

Ambil informasi channel. Mengembalikan 50 channel per halaman. Tanpa channel, respons berupa array. Dengan channel, respons berupa satu objek channel.

Parameter Query

• app_id: Wajib. ID aplikasi Anda
• page: Opsional. Nomor halaman untuk paginasi
• channel: Opsional. Nama channel spesifik yang akan diambil

Contoh Request

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

Tipe Response

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 adalah shortcut hanya-input dan tidak dikembalikan. Rollout yang dijeda direpresentasikan oleh nilai non-null rolloutPausedAt.

Contoh Response

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

HAPUS

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

Hapus channel. Perhatikan bahwa ini akan memengaruhi semua perangkat yang menggunakan channel ini.

Body Request

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

Contoh Request

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/

Respons Sukses

{
  "status": "ok"
}

Bersihkan App Preview

Dengan delete_bundle: true, an app_preview key dapat membersihkan secara atomik hanya channel yang dibuatnya beserta bundle terkait yang tidak dibagikan. key tidak menerima umum bundle.delete izinnya.

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/

Penanganan error

Semua error menggunakan format error standar yang dijelaskan di Ikhtisar API.

Skenario error umum dan responsnya:

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

Kasus Penggunaan Umum

1. Pengujian Beta

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

2. Peluncuran Produksi

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

3. Pembaruan Spesifik Platform

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

Lanjutkan dari Channels

Jika Anda menggunakan Channel untuk merencanakan routing channel dan staged rollout, hubungkan dengan Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Solusi Beta Testing untuk workflow produk di Beta Testing Solution, Solusi Version Targeting untuk workflow produk di Version Targeting Solution, dan Praktik Terbaik Environment Capgo: Staging dengan Satu Mobile App ID untuk konteks praktis dalam Capgo Environment Best Practices: Staging dengan Satu Mobile App ID.