Daftar checklist pengaturan sekali

Anda telah selesai onboarding. Sekarang konfigurasi Capgo satu kali. Setelah itu, pekerjaan sehari-hari hanya unggah → tes → rilis.

Rilis versi toko baru terlebih dahulu

Menginstal plugin Capgo di proyek Anda tidak cukup. OTA updates hanya berfungsi pada perangkat yang menjalankan aplikasi asli yang sudah termasuk plugin.

Setelah Anda menambahkan Capgo dan memanggil CapacitorUpdater.notifyAppReady():

1. Run npx cap sync
2. Buat aplikasi iOS / Android baru
3. Kirimkan ke App Store, Play Store, TestFlight, atau distribusi internal Anda

Pengguna pada versi aplikasi toko yang lebih tua tanpa plugin akan tidak pernah menerima update live. Mengunggah bundle ke Capgo hanya mempengaruhi perangkat pada aplikasi Capgo-dihubungkan.

Lihat juga troubleshooting.

Aturan: saluran adalah jalur rilis (development, productionTidak ada tiket, fitur, atau nama pengembang.

---

Daftar Persiapan Satu Kali

1. Buat SaluranPilih set terkecil yang sesuai (lihat di bawah).

2. Atur Saluran Unggah Default di Pengaturan Aplikasi:

   • Aplikasi Solo → production
   • Tim → development

3. Saluran Produksi: publik on, perangkat self-set off, blokir update di native on, pengaman auto-update on major.

4. Saluran uji (development / staging: publik off, perangkat self-set on untuk QA.

5. Upload dari CI dengan --delta (checksum dan dependensi native otomatis):

   npx @capgo/cli@latest bundle upload \
     --channel development \
     --bundle "1.8.0-${BUILD_NUMBER}" \
     --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
     --delta

   The --bundle nilai harus sah versi semantik. Validasi sebelum mengunggah. Pengujian SemVer sebelum mengunggah.

6. Tunggu sampai Anda melakukan pengujian, dari dashboard atau __CAPGO_KEEP_0__. or CLI.

7. undang sekali, setidaknya hak akses yang minimal, 2FA untuk organisasi, satu __CAPGO_KEEP_0__ kunci di CI. for the org, one API key in CI.

Leave encryption, min_update_versionmetadata, dan pratinjau mati kecuali Anda memiliki alasan yang jelas.

---

Pilih ukuran Anda

Sederhana: 1 aplikasi, 1 saluran: production

Tim: development + production. Unggah ke dev, distribusikan ke prod.

Versi asli: tambahkan saluran hanya jika diperlukan, misalnya production-9.0 + test-9.0. Tahan pengguna toko di saluran produksi utama.

Banyak aplikasi: model sederhana yang sama per aplikasi (biasanya satu production ). Jangan membuat saluran tambahan hanya karena organisasi besar.

Peluncuran kereta (opsional): staging → rc → production. Template yang sama di setiap aplikasi yang membutuhkannya.

Peringatan

Jangan menggunakan saluran yang dinamai tiket, orang, atau variabel CI seperti ${inputs_capgo_channel}.

---

Nama paket vs komentar

Nama paket adalah diperlukan untuk diikuti versi semantik. Capgo menggunakan semver untuk pengecekan kompatibilitas, aturan auto-update kanal, dan rollback. Validasi setiap nama dalam Pengujian SemVer sebelum unggah.

• Nama = semver dari CI, misalnya 1.8.0, 1.8.0-beta.1atau 1.8.0-20260629.42
• Komentar = teks bebas untuk manusia → commit abc1234 run 28059070270

Gunakan semver versi pra-rilis label (bagian setelah -) ketika Anda mengirim banyak build di bawah versi yang sama MAJOR.MINOR.PATCH. Misalnya, simpan 1.8.0 dan tambahkan tanggal atau penomoran build di pre-release: 1.8.0-20260629.1, 1.8.0-beta.2. Jangan menciptakan format kustom seperti fix-login-bug atau 2.5.2026062306. Mereka tidak valid semver dan akan gagal atau berperilaku tidak terduga.

Tulis catatan rilis di --comment, bukan di nama bundle.

Lihat juga target versi dan versi bundel.

---

Mengunggah Delta

--delta mengunggah manifest jadi perangkat hanya mengunduh file yang berubah saja bukan bundel lengkap setiap kali. Ceksum selalu dihitung secara otomatis. Anda tidak perlu memasukkan flag ceksum.

Default: --delta (manifest + zip backup)

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

Ini adalah rekomendasi default yang paling umum untuk aplikasi-aplikasi tersebut. Capgo menyimpan manifest dan menyimpan zip lengkap sebagai cadangan. Baik ketika biaya penyimpanan bukanlah kekhawatiran utama.

Penyimpanan menyimpan: --delta-only

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta-only

Gunakan --delta-only ketika Anda ingin mengurangi Capgo penyimpanan. Hanya file delta/manifest yang disimpan, bukan zip lengkap. Pilih ini untuk aplikasi besar atau volume unggah tinggi di mana penyimpanan menambahkan biaya.

Kompromi: tanpa cadangan zip di server, Anda bergantung sepenuhnya pada jalur manifest. Lebih baik diabaikan --delta-only kecuali Anda memang membutuhkan penyimpanan yang lebih sedikit.

Tidak diperlukan pengaturan plugin tambahan pada perangkat. Pembarui membaca manifest dan mengambil file yang berubah hanya.

Tip

Lihat Pembaruan delta untuk troubleshooting dan directUpdate perilaku.

---

Alur harian

Upload to development (--delta)
  → test
  → deploy to production
  → don't touch channel settings again

---

Kesalahan umum

Kesalahan	Pemecahan masalah
Mengharapkan OTA sebelum rilis toko baru	Rebuild dan kirimkan aplikasi native setelah menambahkan plugin
Mengunggah bundle tetapi tidak mengirimkan ke saluran	Tetapkan bundle ke saluran (misalnya production)
Saluran per fitur, tiket, atau pengembang	Gunakan jalur rilis permanen hanya
Nama saluran CI dinamis	Nama-nama yang tetap: development, production
Terlalu banyak saluran untuk aplikasi sederhana	Mulai dengan 1-2 saluran
Perangkat menetapkan sendiri ke produksi	Matikan untuk produksi, nyalakan untuk saluran uji
Mengabaikan --delta	Tambahkan --delta ke unggahan; gunakan --delta-only hanya ketika Anda perlu menyimpan penyimpanan
Nama bundel non-semver	Ikuti versi semantik dan validasi di Pengujian SemVer
Mengubah skema versi waktu	Tetapkan semver; gunakan label pra-rilis untuk build tambahan (1.8.0-20260629.1)
Metadata / diaktifkan tanpa alasan	Ditangguhkan secara default

---

Pelajari lebih lanjut

Saluran Default, urutan, dan routing.

Perbarui delta Mengapa dan bagaimana menggunakan --delta.

CI/CD Automatis upload dan deploy.

Paketan Checksum, dependensi, dan metadata.