Kompatibilitas Native

Sebuah Capgo live update menggantikan bundle JavaScript secara instan, tetapi tidak dapat mengubah native bagian dari aplikasi Anda — plugin Capacitor/Cordova, dependensi native, dan konfigurasi proyek native yang dikompilasi ke dalam biner yang terpasang. Ketika bundle baru mengharapkan code native yang tidak dimiliki oleh biner yang terpasang, bundle tersebut menjadi native-incompatible: Capgo masih dapat mengirimkannya, tetapi mungkin crash atau berperilaku tidak normal pada perangkat yang masih menjalankan build native yang lebih lama.

Halaman ini menjelaskan bagaimana Capgo mendeteksi kompatibilitas native, apa arti pembaruan yang tidak kompatibel bagi pengguna Anda, dan cara mengirim perubahan native dengan aman.

Catatan

Live updates terbatas pada perubahan bundle JavaScript. Jika Anda perlu memperbarui code native — menambahkan atau menghapus plugin, meng-upgrade Capacitor, atau mengubah konfigurasi proyek native — Anda perlu mengirim build biner baru melalui proses distribusi app store yang biasa.

TLDR: OTA atau native?

Capgo dapat mengirim file dari folder web build yang Anda hasilkan. Jika perubahan hanya memengaruhi HTML, CSS, JavaScript, aset, atau paket pure-JavaScript yang dibundel ke dalam output tersebut, kirimkan sebagai live update.

Gunakan rilis aplikasi native ketika perubahan memperbarui capacitor.config.ts, konfigurasi plugin yang disimpan di config Capacitor, plugin atau dependensi native, Capacitor itu sendiri, atau file proyek iOS/Android. Cek praktis: jika perubahan tersebut harus memperbarui proyek native melalui npx cap sync atau npx cap copy sebelum perangkat yang sudah terinstal dapat menggunakannya, anggap itu native.

Perubahan	Rilis dengan Capgo OTA?	Mengapa
HTML, CSS, JavaScript aplikasi, gambar, font, dan aset build web lainnya	Ya	Mereka dimuat dari web bundle saat runtime.
Perubahan paket Pure-JavaScript yang di-bundle ke output web Anda	Ya	JavaScript yang dihasilkan adalah bagian dari web bundle.
capacitor.config.ts perubahan	Tidak	Konfigurasi Capacitor dibaca ke aplikasi native saat build.
Menambahkan, menghapus, atau meng-upgrade plugin Capacitor/Cordova	Tidak	Binary native yang terinstal harus berisi code native yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada memerlukan binary baru dari store.

Plugin client berdasarkan stack

Capgo menyediakan klien updater khusus untuk setiap runtime hybrid:

Plugin	Gunakan saat
@capgo/capacitor-updater	Aplikasi iOS/Android Capacitor
@capgo/cordova-updater	Aplikasi Cordova iOS 7+ / Android 13+
@capgo/electron-updater	Aplikasi desktop Electron

Pemeriksaan kompatibilitas native berlaku terlepas dari plugin klien — membandingkan dependensi native yang tercatat dalam bundle dengan biner yang terpasang.

Mengapa kompatibilitas native itu penting

Setiap aplikasi Capacitor dirilis dalam dua lapisan:

• Panduan biner native diinstal pengguna dari App Store / Play Store. Berisi Capacitor, plugin native Anda, dan konfigurasi native.
• Panduan bundle JavaScript (web app Anda) yang dapat diperbarui Capgo secara over-the-air.

Sebuah live update hanya mengganti lapisan JavaScript. Jika JavaScript baru tersebut memanggil plugin native atau API yang tidak dikompilasi ke dalam binary yang terpasang, pemanggilan akan gagal saat runtime — yang dapat menyebabkan crash aplikasi atau merusak fitur secara diam-diam. Singkatnya: Capgo tidak dapat memperbarui code native, sehingga perangkat yang menjalankan build native lama tidak dapat menjalankan bundle yang dibangun berdasarkan code native baru dengan aman.

Cara Capgo mendeteksi kompatibilitas

Saat Anda mengunggah bundle — atau menjalankan pemeriksaan secara manual — Capgo membandingkan paket native di proyek lokal Anda (plugin Capacitor/Cordova Anda dan versinya) dengan paket native yang tercatat untuk bundle yang saat ini aktif di channel:

• Jika cocok, perubahannya hanya JavaScript dan aman untuk dikirim secara over-the-air.
• Jika plugin ditambahkan, dihapus, atau versi diubah, bundle tersebut native-incompatible — perubahan tersebut hanya berlaku setelah pengguna menginstal binary native baru.

Periksa dari CLI

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

CLI menampilkan tabel setiap native package beserta versi lokal, versi yang aktif di channel, dan statusnya:

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

Tips

Tambah --text untuk mengganti emoji dengan OK/FAIL (berguna di logs CI), dan --package-json / --node-modules untuk menunjuk ke path yang tepat di monorepo.

Dapatkan hasil yang dapat dibaca mesin (CI)

Untuk pipeline, bundle releaseType meringkas pengecekan menjadi satu kata:

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

Gunakan ini sebagai gate pipeline rilis Anda: kirim live update saat muncul OTA, dan picu native build saat muncul native.

Arti update yang tidak kompatibel bagi pengguna Anda

Peringatan

Secara default, mendeteksi ketidakkompatibelan tidak tidak memblokir upload — jika Anda mengunggah bundle yang tidak kompatibel secara native dan menyetelnya sebagai build aktif channel, Capgo akan menyampaikannya ke perangkat di channel tersebut. (Anda dapat mengubah ini menjadi gerbang keras dengan --fail-on-incompatible — lihat Cegah pengiriman yang tidak kompatibel di bawah.)

Pada perangkat yang masih menjalankan native binary lama, native code yang hilang dapat menyebabkan crash atau fitur rusak — meskipun update berhasil diunduh dan diterapkan. Inilah mengapa live update bisa live dan terkirim, tetapi tetap merusak aplikasi bagi pengguna lama, dan mengapa Capgo dapat memberi peringatan saat bundle yang tidak kompatibel dirilis.

Capgo rollback otomatis dapat menangkap error JavaScript yang dilempar sebelum notifyAppReady() berjalan, tetapi bukan pengganti untuk mengirim native code yang kompatibel — ketidakcocokan yang menyebabkan crash kemudian, atau crash native, bisa lolos darinya.

Cara merilis perubahan native dengan aman

Terbitkan Native Build baru (solusi sebenarnya)

Ketika bundle membutuhkan native code baru, build dan kirim binary baru ke App Store / Play Store (atau build ulang dengan Capgo Cloud Build). Setelah pengguna memperbarui binary, dependensi native bundle akan selaras dan live update berjalan dengan benar.

Rollback jika bundle yang tidak kompatibel sudah live

Jika bundle yang tidak kompatibel sudah aktif di sebuah channel, kembalikan channel ke build kompatibel terakhir untuk menghentikan penyajiannya hingga native build tersedia. Lihat Rollback.

Cegah pengiriman yang tidak kompatibel

Dua pengaman yang saling melengkapi, keduanya benar-benar memeriksa native package Anda:

Gagalkan upload di CI — --fail-on-incompatible

Tambahkan flag ke bundle upload langkah. Jika paket native bundle tidak sesuai dengan versi yang sedang live di channel tersebut, proses upload gagal dengan non-zero exit dan tidak ada yang dikirim — sehingga pipeline Anda mencegah Anda memublikasikan OTA update secara diam-diam yang tidak bisa berlaku sampai user menginstal native build:

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

Upload yang kompatibel — serta kondisi saat pengecekan tidak bisa berjalan (channel baru, atau tidak ada metadata remote) — tetap diteruskan tanpa perubahan. Di terminal interaktif, sistem akan menawarkan alur native-build Capgo Builder sebagai gantinya; menolak akan menggagalkan proses. (Tidak bisa digabungkan dengan --ignore-metadata-check.)

Tips

Saat Anda dengan sengaja membutuhkan bundle yang berbeda dari paket native live di channel (plugin baru, upgrade Capacitor, dll.), hilangkan --fail-on-incompatible untuk upload baseline tersebut. Pertahankan flag di CI OTA harian. Alur kerja channel lengkap: Alur Kerja Channel Native + OTA.

Batasi pengiriman berdasarkan versi native — metadata + --auto-min-update-version

Saat Anda lakukan ship native build dan bundle secara bersamaan, letakkan channel di metadata strategi dan upload dengan --auto-min-update-version. Capgo menjalankan pengecekan kompatibilitas pada setiap upload dan, saat bundle membutuhkan native code baru, menaikkan batas minimum update agar perangkat yang belum menginstal native build yang sesuai tidak menerimanya:

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

Peringatan

Aturan nomor versi seperti --disable-auto-update major adalah tidak pengganti — mereka hanya memblokir lompatan versi dan tidak pernah memeriksa native code, jadi perubahan native dalam rilis minor atau patch tetap terkirim. Gunakan --fail-on-incompatible atau --auto-min-update-version, yang memeriksa package native Anda.

Lihat Targeting Versi untuk daftar lengkap opsi targeting.

Terkait

Workflow Native + OTA

Channel dev/production, kapan harus dipertahankan, --fail-on-incompatibledan cara merilis native baseline yang terencana.

Auto OTA atau Native

Hubungkan bundle releaseType ke GitHub Actions atau GitLab agar CI memilih live update vs Capgo Build.

Targeting Versi

Kirim hanya bundle yang kompatibel menggunakan channel, aturan semver, dan strategi metadata.

Rollback

Kembalikan channel ke build kompatibel terakhir jika bundle yang tidak kompatibel sudah live.

Tipe Update

Bagaimana apply timing, kondisi delay, dan version blocking bekerja bersama.

CLI: bundle

Referensi untuk kompatibilitas bundle, releaseType, dan opsi upload.

Lanjut dari Native Compatibility

Jika Anda menggunakan Kompatibilitas Native untuk menjaga Live Update tetap aman, hubungkan dengan Targeting Versi untuk merutekan bundle berdasarkan versi native, Rollback untuk pemulihan saat bundle yang tidak kompatibel dikirim, Tipe Update untuk memahami pemblokiran versi channel, dan referensi bundle Capgo CLI untuk perintah compatibility dan releaseType.