Channel

Channel adalah mekanisme inti untuk mengelola update aplikasi di Capgo. Dengan channel, Anda bisa mengatur cara dan kapan user menerima update, termasuk fitur seperti A/B testing, staged rollouts, dan update khusus platform.

Memahami Channels

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

• Kontrol Bundle (versi): Menentukan bundle (versi) mana yang diterima user
• Targeting Platform: Targetkan platform spesifik (iOS/Android/Electron)
• Kebijakan Update: Mengatur cara pengiriman update
• Restriksi Perangkat: Kelola perangkat mana saja yang bisa mengakses update

Opsi Konfigurasi Channel

• public: Atur sebagai channel default untuk perangkat baru.
• disableAutoUpdateUnderNative: Cegah update jika versi native app di perangkat lebih baru dari stable bundle di channel ini.
• disableAutoUpdate: Kontrol perilaku update (major, minor, patch, version_number, atau none). metadata diterima sebagai alias dari version_number.
• updatePackage: Kontrol 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.
• izinkan_perangkat_set_sendiri: Biarkan perangkat memilih channel mereka sendiri.
• izinkan_emulator, izinkan_perangkat, izinkan_dev, izinkan_prod: Kontrol perangkat dan tipe build mana yang menerima update.
• Rollout bertahap: Jaga bundle tetap stabil sambil mengekspos target bundle ke cohort tertentu. Lihat Rollout bertahap.

Praktik Terbaik

1. Testing Channel: Gunakan testing channel untuk validasi internal
2. Staged Rollout: Gunakan beberapa channel untuk deployment update secara 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, responsnya berupa array. Dengan channel, responsnya berupa satu objek channel.

Parameter Query

• app_id: Wajib. ID aplikasi Anda
• page: Opsional. Nomor halaman untuk paginasi
• channel: Opsional. Nama channel spesifik untuk 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 input-only 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. Perlu dicatat bahwa ini akan berdampak pada 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"
}

Pembersihan App Preview

Dengan delete_bundle: true, sebuah app_preview key hanya bisa membersihkan secara atomik channel yang dibuatnya sendiri beserta bundle terkait yang tidak dibagikan. Key tersebut tidak menerima 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. Rilis Produksi

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

3. Update 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.