Kompatibilitas Asli

Sebuah Capgo pembaruan hidup mengganti bundel aplikasi Anda secara instan, tetapi tidak dapat mengubah bagian asli aplikasi Anda — plugin Cordova /Cordova __CAPGO_KEEP_0__, ketergantungan asli, dan konfigurasi proyek asli yang dikompilasi ke dalam file biner yang diinstal. Ketika sebuah bundel baru mengharapkan __CAPGO_KEEP_1__ asli yang tidak ada di dalam file biner yang diinstal, bundel tersebut adalah part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is tidak kompatibel dengan asli: Capgo masih bisa mengirimkannya, tapi mungkin akan mengalami crash atau perilaku tidak normal pada perangkat yang masih menjalankan versi native yang lebih lama.

Ini halaman yang menjelaskan bagaimana Capgo mendeteksi kompatibilitas native, apa artinya update tidak kompatibel bagi pengguna, dan bagaimana mengirimkan perubahan native dengan aman.

Catatan

Pembaruan live terbatas pada perubahan bundle JavaScript. Jika Anda perlu mengupdate native code — menambahkan atau menghapus plugin, meningkatkan Capacitor, atau mengubah konfigurasi proyek native — Anda akan perlu mengirimkan build biner baru melalui proses distribusi aplikasi biasa.

Ringkasan: OTA atau native?

Capgo bisa mengirim file dari folder hasil build web yang dihasilkan. Jika perubahan hanya mempengaruhi HTML, CSS, JavaScript, asset, atau paket JavaScript murni yang dibundel ke dalam output tersebut, kirimkannya sebagai pembaruan live.

Pakai rilis aplikasi native ketika perubahan mengupdate capacitor.config.ts, konfigurasi plugin yang disimpan di Capacitor config, plugin native atau dependensi, Capacitor sendiri, atau file proyek iOS/Android. Cek praktis: jika perubahan harus mengupdate proyek native melalui npx cap sync atau npx cap copy sebelum perangkat yang sudah terinstal bisa menggunakannya, anggaplah sebagai native.

Ubah	Apakah Anda ingin mengirimkan Capgo OTA?	Mengapa
HTML, CSS, JavaScript aplikasi, gambar, font, dan aset web lainnya untuk pembangunan	Ya	Mereka dimuat dari bundle web pada saat runtime.
Paket JavaScript murni yang berubah dibundel ke dalam output web Anda	Ya	JavaScript yang dihasilkan merupakan bagian dari bundle web.
capacitor.config.ts perubahan	Tidak	Konfigurasi Capacitor dibaca ke dalam aplikasi native pada saat waktu pembangunan.
Mengambah, menghapus, atau memperbarui plugin Capacitor/Cordova	Tidak	File biner native yang diinstal harus mengandung code yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada membutuhkan binary baru dari toko.

Plugin klien oleh stack

Capgo mengirimkan klien pembarui yang spesifik untuk setiap runtime hybrid:

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

Periksa kompatibilitas native berlaku terlepas dari plugin klien — mereka membandingkan ketergantungan native yang direkam dalam bundle dengan binary yang terinstal.

Mengapa kompatibilitas native penting

Setiap aplikasi Capacitor dikirim dalam dua lapisan:

• Biner native pengguna menginstal dari App Store / Play Store. Ini berisi __CAPGO_KEEP_0__, plugin native Anda, dan konfigurasi native. users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• (aplikasi web Anda) yang __CAPGO_KEEP_0__ dapat memperbarui secara nirkabel. Aplikasi __CAPGO_KEEP_0__ dikirim dalam dua lapisan: (your web app) that Capgo can update over the air.

A pembaruan live hanya mengganti layer JavaScript. Jika JavaScript baru tersebut memanggil plugin native atau API yang tidak dikompilasi ke dalam binary yang terpasang, panggilan gagal pada waktu runtime — yang dapat menyebabkan aplikasi crash atau menghentikan fitur secara diam-diam. Dengan kata sederhana: Capgo tidak dapat memperbarui plugin native code, sehingga perangkat yang menjalankan build native lama tidak dapat menjalankan bundle yang dibangun terhadap plugin native code baru.

Bagaimana Capgo mendeteksi kompatibilitas

Saat Anda mengunggah bundle — atau menjalankan cek secara manual — Capgo membandingkan plugin native in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle saat ini berada di saluran:

• Jika mereka cocok, perubahan hanya JavaScript dan aman untuk dikirimkan secara nirkabel.
• Jika plugin ditambahkan, dihapus, atau versi berubah, bundle adalah tidak kompatibel dengan native — perubahan tersebut hanya efektif setelah pengguna menginstal binary native baru.

Periksa dari CLI

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

CLI mencetak tabel dari setiap paket native dengan versi lokal, versi yang hidup di saluran, dan status:

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

Tambahkan --text untuk mengganti emoji-emoji untuk OK/FAIL (terutama berguna dalam log CI), dan --package-json / --node-modules untuk menunjuk ke jalur yang tepat dalam repositori monorepo.

Dapatkan sebuah keputusan yang dapat dibaca mesin (CI)

Untuk pipa-pipa, bundle releaseType menggabungkan periksaan 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

Tutupkan pipa rilis Anda dengan ini: kirimkan pembaruan hidup ketika mencetak OTA, dan trigger build asli ketika mencetak native.

Apa artinya pembaruan tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak akan menghalangi unggahan — jika Anda mengunggah bundle native tidak kompatibel dan menetapkannya sebagai bangunan aktif saluran, __CAPGO_KEEP_0__ akan mengirimkannya ke perangkat pada saluran tersebut. (Anda dapat mengubah ini menjadi pintu keras dengan — lihat di bawah Prevent pengiriman tidak kompatibel.) tidak block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo Pada perangkat yang masih menjalankan biner native yang lebih tua, __CAPGO_KEEP_0__ native yang hilang dapat menyebabkan kacau atau fitur rusak — meskipun pembaruan yang diunduh dan diterapkan “berhasil.” Ini adalah mengapa pembaruan live dapat live dan dikirimkan namun masih dapat mengganggu aplikasi untuk pengguna yang sudah ada, dan mengapa __CAPGO_KEEP_1__ dapat memberi peringatan Anda ketika bundle tidak kompatibel berada di live. __CAPGO_KEEP_0__’s --fail-on-incompatible di di di

di di, the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo’s rollback otomatis mengenai kesalahan JavaScript yang dilempar sebelumnya notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

Bagaimana mengirimkan perubahan native dengan aman

Publish perubahan native baru (solusi sebenarnya)

Ketika sebuah bundle membutuhkan native code, bangun dan kirimkan binary baru ke App Store / Play Store (atau bangun ulang dengan Capgo Cloud Build). Setelah pengguna memperbarui binary, dependensi native bundle berbaris dan live update berjalan dengan benar.

Mengembalikan ke versi sebelumnya jika bundle tidak kompatibel sudah aktif

Jika bundle tidak kompatibel sudah aktif di sebuah saluran, kembalikan saluran ke versi terakhir yang kompatibel untuk menghentikan pelayanan hingga perubahan native keluar. Lihat Mengembalikan.

Mencegah pengiriman tidak kompatibel

Dua pengawas komplementer, yang sebenarnya memeriksa paket native Anda:

Gagal unggah di CI — --fail-on-incompatible

Tambahkan flag ke langkah Anda. Jika paket native bundel tidak sesuai dengan versi yang sedang berjalan di saluran, unggahan bundle upload Gagal dengan kode keluaran tidak nol dan tidak ada yang dikirim — sehingga pipa Anda mencegah Anda menerbitkan pembaruan OTA diam-diam yang tidak dapat berlaku sampai pengguna menginstal build native: Jendela terminal Salin ke clipboard

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

Compatible uploads — and cases where the check can’t run (a new channel, or no remote metadata) — pass through unchanged. In an interactive terminal it offers the Capgo Builder native-build flow instead; declining fails. (Can’t be combined with --ignore-metadata-check.)

Mencegah pengiriman oleh versi native — metadata + --auto-min-update-version

When Anda melakukan build native dan bundle bersama, masukkan saluran ke strategi dan unggah dengan __CAPGO_KEEP_0__. lakukan strategi metadata dan --auto-min-update-versionCapgo melakukan pengecekan kompatibilitas pada setiap unggahan dan, ketika bundle memerlukan native code baru, meningkatkan lantai update sehingga perangkat yang belum menginstal build native yang sesuai tidak menerima update tersebut:

# 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 __CAPGO_KEEP_1__ --disable-auto-update major tidak ada sebuah pengganti — mereka hanya menghalangi lonjakan versi dan tidak pernah memeriksa code, jadi perubahan asli yang dikirimkan dalam rilis minor atau patch masih keluar. Gunakan --fail-on-incompatible atau --auto-min-update-version, yang memeriksa paket native Anda.

Lihat Target Versi untuk set lengkap opsi target.

Terhubung

Target Versi

Sampaikan hanya bundle yang kompatibel menggunakan saluran, aturan semver, dan strategi metadata.

Rollbacks

Tetapkan kembali saluran ke build yang kompatibel terakhir jika bundle yang tidak kompatibel keluar.

Jenis Update

Bagaimana cara aplikasi waktu, kondisi delay, dan pemblokiran versi bekerja sama.

CLI: bundle

Referensi untuk kompatibilitas bundle, releaseType, dan opsi unggah.

Lanjutkan dari Kompatibilitas Asli

Jika Anda menggunakan Kompatibilitas Asli untuk menjaga pembaruan hidup aman, hubungkannya dengan Target Versi untuk mengarahkan bundle berdasarkan versi native, Rollbacks untuk memulihkan ketika bundle yang tidak kompatibel dikirimkan, Jenis Update untuk memahami versi saluran yang menghalangi, dan Capgo CLI referensi bundle untuk perintah kompatibilitas dan releaseType.