Channel

Baru dengan channels? Tonton tiga walkthrough singkat tentang channel untuk melihat default routing, self-assignment perangkat, dan override konsol dalam praktik.

Panduan @capgo/capacitor-updater tersebut setChannel() dan unsetChannel() dalam panduan ini hanya didukung di Android dan iOS. Mereka tidak mengubah channel routing di pratinjau browser.

Cara Capgo memilih channel (urutan prioritas)

Saat perangkat meminta Capgo untuk update, channel yang digunakan ditentukan berdasarkan urutan berikut (prioritas tertinggi di awal):

1. Pemetaan device paksa: Jika ID perangkat secara eksplisit dipaksa ke channel (yang Perangkat tab di halaman channel), channel itu selalu menang. Forced mapping adalah override console/API. Capgo menghapusnya 90 hari setelah penulisan override terakhir. Lihat Override di Console dan API kedaluwarsa.
2. Cloud override (Dashboard atau Public API): Mengubah channel perangkat di dashboard atau melalui Public API akan menulis override yang terikat pada device ID tersebut. Menginstal ulang aplikasi tidak akan tidak menghapusnya; menghapus override-lah yang melakukannya. Retensi 90 hari yang sama juga berlaku.
3. Plugin setChannel() (lokal): Pada versi plugin saat ini, setChannel() menyimpan channel di perangkat setelah validasi backend. Ini bukan dashboard override. Pada Android dan iOS dengan updater 8.51.0 ke atas, persistDefaultChannelOnReinstall defaultnya adalah true, sehingga pilihan tersebut hanya bisa bertahan setelah reinstall jika OS memulihkan data aplikasi dan persistDefaultChannelOnReinstall tetap true. Panggil unsetChannel() untuk menghapus pilihan lokal secara eksplisit.
4. konfigurasi Capacitor defaultChannel (default untuk test build): Untuk build internal / beta / test, Anda dapat mengatur defaultChannel (kunci legacy channel) di capacitor.config.* sehingga perangkat test mulai di channel pre-release (mis. beta, pr-123). Jika tidak ada, perangkat akan melanjutkan ke default cloud. Build produksi biasanya tidak mengatur ini.
5. Cloud Default Channel (strategi utama untuk ~99% pengguna): Kanal produksi utama tempat hampir semua pengguna nyata mendarat. Perangkat baru mana pun tanpa force, tanpa override, dan tanpa lokal setChannel(), dan tanpa konfigurasi defaultChannel menggunakan ini. Mengubahnya akan melakukan rollout (atau rollback) untuk semua orang dalam hitungan detik, tanpa perlu binary baru.

Mengapa default cloud adalah jalur utama:

• Rollout atau rollback instan tanpa perlu build ulang atau publish ulang binary native.
• Satu tempat untuk mengelola perilaku iOS, Android, dan Electron.
• Lebih aman: Anda bisa memastikan bundle tersedia dan pengaturan sudah benar sebelum mengganti default.
• Perubahan dapat diaudit (anggota tim bisa melihat siapa yang mengubah apa di UI / logs). Prinsip desain: Layer di atasnya (force / override / config) adalah pengecualian (debug satu user, switching QA, default build test). User normal akan mengikuti default cloud.

Changing the default cloud channel memengaruhi baru perangkat normal yang:

• Tidak dipaksa
• Belum memiliki cloud override
• Tidak memiliki override di level aplikasi defaultChannel yang ditentukan

Jika test build dirilis dengan defaultChannel: 'beta' dan Anda kemudian mengubah cloud default ke production, perangkat yang mulai di beta via config akan tetap di sana sampai ada assignment prioritas lebih tinggi, atau sampai Anda merilis binary tanpa defaultChannel. Menghapus force, cloud override, atau local assignment setChannel() tidak menghapus nilai config; fallback tersebut tetap ada sampai binary baru.

Device tetap di channel saat ini kecuali Anda:

• Paksa mereka pindah ke channel lain (console atau Public API).
• Ubah cloud override di dashboard atau Public API.
• Panggil setChannel() (local assignment pada versi plugin saat ini).
• Hapus / arsipkan channel yang mereka gunakan (lalu mereka akan kembali mengikuti urutan precedence saat pengecekan berikutnya).
• Tunggu hingga override console/API kedaluwarsa setelah 90 hari.
• Panggil unsetChannel() untuk menghapus local assignment setChannel() Ini tidak menghapus override console/API atau yang dikonfigurasi app defaultChannel; prioritas normal berlaku kembali.
• Instal ulang aplikasi, yang dapat menghapus assignment lokal pada versi updater lama atau saat data aplikasi tidak dipulihkan. Pada Android dan iOS dengan updater 8.51.0 ke atas, persistDefaultChannelOnReinstall defaultnya adalah true, sehingga data aplikasi yang dipulihkan hanya dapat mempertahankan pilihan lokal selama opsi ini tetap ada true. Override Console/API tidak terpengaruh.

Jika sebuah channel dinonaktifkan untuk suatu platform (lihat toggle iOS / Android / Electron) dan seharusnya akan terpilih, pemilihan akan melewatinya dan beralih ke aturan berikutnya.

Catatan: Mengatur defaultChannel berarti mengubahnya memerlukan binary baru; gunakan secara sengaja untuk test/QA, bukan untuk kontrol produksi umum.

Contoh konfigurasi Capacitor

capacitor.config.ts

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

Jika nanti Anda mengubah default dashboard ke production, perangkat yang sudah ada di channel lain (via config, override, atau force) TIDAK akan pindah otomatis; hanya perangkat baru (atau yang override/force-nya Anda hapus) yang akan mengikutinya.

---

Mengelola channel

Pertama, mari kita lihat halaman channels. Anda bisa mengaksesnya dengan mengklik aplikasi Anda lalu mengklik tab channels.

Membuat channel

Seperti yang Anda lihat, ada tombol plus di pojok kanan bawah. (1 di gambar) Mengkliknya akan membuka modal untuk membuat channel baru.

Lalu setelah Anda mengklik Add channel baru seharusnya muncul di daftar.

Apa arti misconfigured?

Terkadang konfigurasi channel tidak valid. Jika demikian, Anda akan melihat peringatan besar dan Misconfigured kolom akan bertuliskan Yes untuk satu atau lebih channel. Anda dapat mempelajari lebih lanjut tentangnya di sini

Menghapus channel

Untuk menghapus channel dari web app, buka Channel tab aplikasi Anda dan cari baris channel. Di Aksi kolom, klik ikon tempat sampah, lalu klik Hapus di dialog konfirmasi.

Jika ikon tempat sampah tidak terlihat, akun Anda tidak memiliki channel.delete izin untuk aplikasi tersebut. Minta admin organisasi atau aplikasi untuk memberi peran yang dapat menghapus channel, atau hapus channel dengan key API yang punya izin:

npx @capgo/cli@latest channel delete <channel-name> <app-id>

Terikat pada organisasi dan aplikasi Pratinjau Aplikasi key hanya dapat menghapus secara atomik channel preview non-publik dan bundle yang dibuat dengannya channel delete <preview-channel> <app-id> --delete-bundle. Tidak dapat mengubah atau menghapus channel default/utama yang sudah ada, channel dari preview key lain, atau bundle dari key lain. Lihat Kunci API untuk setup least-privilege.

Mengelola channel

Klik nama channel untuk membuka halaman channel. Ini halaman penuh dengan tab, bukan modal.

Tab channel

• Dashboard: Adopsi bundle saat ini dan statistik instalasi untuk channel ini.
• Informasi: Pengaturan channel di bawah ini, ditambah progressive rollout dan Test Update API.
• Perangkat: Pemetaan paksa yang dibuat hanya dari konsol atau Public API. Ini tidak menampilkan semua perangkat yang saat ini ada di channel, dan tidak menampilkan perangkat yang menggunakan setChannel(). Lihat Override di Console dan API kedaluwarsa.
• Riwayat: Perubahan pengaturan dan bundle untuk channel ini.
• Pratinjau: Preview bundle yang ditautkan di browser dan native. Aktifkan preview bundle di Informasi Aplikasi pertama.

Pengaturan informasi

Tetap di tab Informasi . Pengaturan muncul dengan urutan berikut:

Pertama, Channel download default adalah status badge, bukan toggle. Aktif berarti channel ini adalah default cloud untuk perangkat baru. Klik Kelola di pengaturan aplikasi untuk mengubah default pada Informasi Aplikasi. Untuk default khusus platform (satu untuk iOS, satu untuk Android, dan satu untuk Electron), lihat bagian yang sama.

Kedua adalah IOS pengaturan. Jika ini false, perangkat iOS tidak akan diizinkan untuk download update dari channel ini.

Ketiga adalah Android pengaturan. Jika ini false, perangkat Android tidak akan diizinkan untuk download update dari channel ini.

Keempat adalah Electron pengaturan. Jika ini false, aplikasi Electron tidak akan diizinkan untuk download update dari channel ini.

Kelima adalah Disable auto downgrade under native pengaturan. Jika ini true, Anda tidak akan bisa downgrade dari versi native. Artinya, jika Anda sudah mengunggah sebuah 1.2.0 versi ke App Store atau Play Store dan mencoba mengatur versi channel ke 1.1.0 maka update (downgrade) tersebut akan gagal.

Keenam adalah Disable auto update. Pengaturan ini cukup kompleks, dan Anda bisa mempelajari lebih lanjut tentang di sini

Ketujuh adalah Download format . Ini menentukan apakah perangkat mengunduh file zip penuh, hanya file delta yang berubah, atau kombinasi terbaik keduanya. Lihat Format download.

Kedelapan adalah Allow development buildJika ini bernilai true, maka development build diizinkan untuk mengunduh update dari channel ini. Jika tidak, setiap permintaan update yang memiliki prod diatur ke false akan ditolak. Ini sangat berguna untuk keperluan testing.

Ninth adalah Allow production build. Jika ini false, build production (store) tidak akan menerima update dari channel ini. Biarkan aktif untuk channel yang melayani pengguna nyata.

Kesepuluh adalah Allow Emulators. Jika ini bernilai false, maka Capgo akan menolak semua permintaan update yang datang dari emulator. Ini biasanya berguna untuk keperluan testing.

Kesebelas adalah Allow physical devices. Jika ini false, Capgo akan menolak request update dari ponsel dan tablet asli. Biarkan aktif untuk channel production.

Kedua belas adalah Allow devices to self dissociate/associate. Jika ini true, maka setChannel method akan tersedia di Android dan iOS. Jika ini di-set ke false dan Anda mencoba memanggil setChannel dengan channel ini maka pemanggilan akan gagal.

Tes Update API

Di bagian bawah Informasi tab, buka Tes Update API. Capgo menampilkan perintah curl terhadap /updates untuk perangkat sampel di channel ini.

Perubahan dapat memakan waktu hingga 60 detik untuk muncul di API karena caching. Jika channel tidak dapat diuji, konsol akan memberi peringatan: channel membutuhkan setidaknya satu platform (iOS atau Android), build produksi, perangkat fisik, dan harus menjadi channel download default atau mengizinkan self-assignment perangkat.

Kirim notifikasi update

Setelah Anda mengubah bundle yang terhubung, konsol dapat meminta untuk Kirim notifikasi update. Ini mengantri silent push agar perangkat di channel tersebut langsung memeriksa bundle baru. Konfigurasi kredensial push Android dan iOS di tab Notifikasi aplikasi terlebih dahulu.

Override di Console dan API kedaluwarsa

Forced mappings dan Dashboard/Public API channel overrides dihapus 90 hari setelah penulisan override terakhir. Check-in perangkat terakhir tidak mereset jam tersebut. Untuk assignment yang bertahan dari pembersihan itu, setel defaultChannel di konfigurasi Capacitor Anda (bertahan setelah reinstall, butuh binary baru untuk diubah) atau panggil setChannel() dari aplikasi Android atau iOS menggunakan @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, atau 8.0.0+ untuk versi mayor plugin Anda. Versi-versi ini menyimpan assignment secara lokal, sehingga menghindari pembersihan 90 hari. Versi sebelumnya menulis override backend yang tunduk pada pembersihan yang sama. Di Android dan iOS dengan updater 8.51.0 ke atas, persistDefaultChannelOnReinstall defaultnya adalah true, jadi pilihan lokal juga bisa bertahan setelah reinstall hanya jika sistem operasi memulihkan data aplikasi dan persistDefaultChannelOnReinstall tetap true. Reinstall dengan persistDefaultChannelOnReinstall: false bisa menghapus pilihan lokal tersebut meskipun data aplikasi dipulihkan. Gunakan unsetChannel() untuk menghapus pilihan lokal tersebut secara eksplisit.

Override retention pada tab Devices di channel. Notifikasi yang sama muncul saat Anda memaksa device ID masuk ke channel.

Ini terpisah dari retensi inventory perangkat. Inventory menghapus perangkat yang tidak terhubung ke Capgo selama 90 hari. Pembersihan override menghapus mapping meskipun perangkat masih aktif. Detail lengkap: Override dari Console dan API kedaluwarsa setelah 90 hari.

Format download

Buka channel dan tetap di Informasi tab. Format download ada di daftar pengaturan, di bawah Disable auto update.

Format unduhan pada tab Informasi channel. Channel baru secara default menggunakan Zip + delta.

Pengaturan ini memilih apa yang dikirim Capgo saat perangkat di channel ini memeriksa pembaruan. Biarkan Zip + delta kecuali Anda perlu memaksa satu jenis.

Label di konsol	Nilai CLI / API	Perangkat yang mengunduh
Zip + delta (default)	all	Setiap perangkat mendapatkan paket terbaik yang didukungnya. Perangkat pada versi plugin dengan dukungan Delta hanya mengunduh file delta yang berubah jika bundle memilikinya. Hanya perangkat pada versi plugin lama tanpa dukungan Delta, atau bundle yang diunggah tanpa file delta, yang kembali ke zip penuh.
Hanya zip penuh	zip	Setiap perangkat mengunduh seluruh zip bundle, bahkan jika file delta ada.
Hanya delta	delta	Hanya file delta yang berubah. Perangkat dengan versi plugin lama yang tidak mendukung Delta tetap menerima zip penuh jika bundle memilikinya.
Zip penuh hanya dari build store	zip_from_builtin	Full zip hanya berlaku selama perangkat masih menggunakan build dari store. Setelah live update pertama, Capgo kembali menyajikan zip + delta.
Delta hanya dari build store	delta_from_builtin	Hanya delta selama perangkat masih menggunakan build dari store. Setelah live update pertama, Capgo kembali menyajikan zip + delta.

Dengan Zip + delta, wajar jika masih terlihat beberapa download full zip. Itu berasal dari perangkat yang masih menjalankan Native Build lama dengan versi plugin tanpa dukungan Delta (di bawah 5.10.0, 6.25.0, atau 7.0.35 untuk versi major-nya). Lihat Update Delta.

Panduan simpan build adalah aset web yang disertakan dalam biner App Store atau Play Store, sebelum update Capgo apa pun. Gunakan from store build only mode saat update pertama dari store build harus full zip saja atau delta saja, dan update berikutnya bisa pakai keduanya.

Capgo tidak akan memasangkan channel zip-only dengan bundle delta-only, atau sebaliknya. Console, CLI, dan Channel API menolak menyimpan dan meminta Anda upload package yang hilang atau mengganti mode.

Anda bisa mengatur nilai yang sama dari CLI. Channel harus sudah ada:

npx @capgo/cli@latest channel set production com.example.app --update-package zip

Nilai yang valid: all, zip, delta, zip_from_builtin, delta_from_builtin.

Rollout bertahap

Channel Informasi tab berisi Rollout bertahap bagian dengan Target rollout dan Fallback stabil, Ubah target rollout, Terapkan persentase, dan aksi Selesaikan rollout, Batalkan rollout, Aktifkan rollout, Nonaktifkan rollout, Jeda rollout, dan Lanjutkan rollout.

Kontrol progressive rollout muncul di bagian atas tab Informasi channel.

Baca Rollout bertahap sebelum mengaktifkannya. Panduan tersebut membahas upload routing (Auto (direkomendasikan) / Target rollout / Ganti stable; CLI --stable / API target: "stable" untuk override), Channel ini menggunakan progressive rollout dialog bundle-link, dan workflow yang aman dengan Observe dan Wawasan Log.

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.