Kompatibilitas Nativ

A Capgo pembaruan live mengganti bundel JavaScript aplikasi Anda Bundel JavaScript tetapi tidak dapat mengubah bagian native aplikasi — plugin Cordova __CAPGO_KEEP_0__, dependensi native, dan konfigurasi proyek native yang dikompilasi ke dalam file biner yang diinstal. Ketika bundel baru memerlukan __CAPGO_KEEP_1__ native yang tidak ada di file biner yang diinstal, bundel tersebut tidak kompatibel dengan native 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 Ini halaman menjelaskan bagaimana __CAPGO_KEEP_0__ mendeteksi kompatibilitas native, apa artinya pembaruan tidak kompatibel bagi pengguna Anda, dan bagaimana mengirimkan perubahan native dengan aman.: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

Ringkasan: OTA atau native?

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

__CAPGO_KEEP_1__

Capgo dapat mengirimkan file dari folder pembangunan web yang dihasilkan. Jika perubahan hanya mempengaruhi HTML, CSS, JavaScript, aset, atau paket JavaScript murni yang dibundel ke dalam output tersebut, kirimkannya sebagai update live.

Pakai rilis aplikasi native ketika perubahan memperbarui capacitor.config.ts, pengaturan plugin yang disimpan di Capacitor konfigurasi, plugin native atau dependensi, Capacitor sendiri, atau file proyek iOS/Android. Periksa secara praktis: jika perubahan harus memperbarui proyek native melalui npx cap sync atau npx cap copy context

Apakah Anda ingin mengirimkan update live atau rilis aplikasi native?	Ship with Capgo OTA?	Perubahan
Apakah Anda ingin mengirimkan update live dengan __CAPGO_KEEP_0__?	Mengapa	HTML, CSS, kode JavaScript aplikasi, gambar, font, dan aset pembangunan web lainnya
Paket JavaScript murni yang berubah dikemas ke dalam output web Anda	Ya	JavaScript yang dihasilkan merupakan bagian dari bundle web.
capacitor.config.ts perubahan	Tidak	Capacitor konfigurasi dibaca ke dalam aplikasi native pada waktu build.
Menambahkan, menghapus, atau mengupgrade Capacitor/Cordova plugin	Tidak	Binary native yang terinstall harus mengandung versi native code yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada memerlukan 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+ Cordova
@capgo/electron-updater	Aplikasi desktop Electron

Pengecekan kompatibilitas native berlaku tanpa peduli dengan plugin klien — mereka membandingkan ketergantungan native yang direkam terhadap bundle dengan binary yang terinstal.

Mengapa kompatibilitas native penting

Setiap aplikasi Capacitor dikirimkan dalam dua lapisan:

• Perangkat asli biner yang diinstal pengguna dari App Store / Play Store. Ini berisi __CAPGO_KEEP_0__, plugin-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. Perbarui hidup hanya mengganti lapisan JavaScript. Jika JavaScript baru tersebut memanggil plugin native atau __CAPGO_KEEP_0__ yang tidak dikompilasi ke dalam biner yang diinstal, panggilan gagal pada waktu runtime — yang dapat menyebabkan aplikasi crash atau menghancurkan fitur secara diam-diam. Dengan sederhana: __CAPGO_KEEP_1__ tidak dapat memperbarui __CAPGO_KEEP_2__ native, sehingga perangkat yang menjalankan build native lama tidak dapat menjalankan bundle yang dibangun atas __CAPGO_KEEP_3__ native baru. Bagaimana Capgo mendeteksi konsistensi

A live update swaps only the JavaScript layer. If that new JavaScript calls a native plugin or API that isn’t compiled into the installed binary, the call fails at runtime — which can crash the app or silently break a feature. Put simply: Capgo cannot update native code, so a device running the old native build can’t safely run a bundle that was built against new native code.

Saat Anda mengunggah bundle — atau menjalankan cek secara manual — Capgo membandingkan

When you upload a bundle — or run the check manually — Capgo compares the __CAPGO_KEEP_0__ 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, paket adalah tidak kompatibel dengan native — perubahan hanya efektif setelah pengguna menginstal biner native baru.

Cek dari CLI

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

CLI mencetak tabel 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

[Tip]

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

[Dapatkan Verifikasi yang Dapat Dibaca Mesin (CI)]

Untuk pipeline, bundle releaseType menggabungkan periksaan menjadi satu kata saja:

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

Jalankan pipelining rilis Anda berdasarkan hal ini: kirimkan pembaruan hidup ketika itu mencetak OTA, dan aktifkan pembangunan asli ketika itu mencetak native.

Apa artinya pembaruan tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak menghalangi unggah — jika Anda mengunggah bundle asli tidak kompatibel dan menetapkannya sebagai bangunan aktif saluran, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo ke perangkat pada saluran itu. (Anda dapat mengubah ini menjadi pintu keras dengan — lihat --fail-on-incompatible — see Prevent pengiriman yang tidak kompatibel di bawah.)

Pada perangkat yang masih menjalankan versi biner asli yang lebih tua biner asli yang lebih tua, code yang hilang dapat menyebabkan kacau atau fitur yang rusak — bahkan meskipun update yang diunduh dan diterapkan “berhasil.” Ini adalah mengapa update live dapat live dan disampaikan namun masih dapat mengganggu aplikasi bagi pengguna yang sudah ada, dan mengapa Capgo dapat memberi peringatan ketika bundle yang tidak kompatibel disampaikan.

Capgo’s rollback otomatis dapat menangkap kesalahan JavaScript yang dilempar sebelum notifyAppReady() berjalan, tetapi tidak dapat menggantikan pengiriman code asli yang kompatibel — kesalahan yang menyebabkan kacau nanti, atau kacau secara native, dapat melewati.

Bagaimana mengirimkan perubahan native dengan aman

Publish perubahan native baru (solusi yang sebenarnya)

Ketika sebuah paket membutuhkan code baru asli, bangun dan kirimkan bangun biner baru ke App Store / Play Store (atau bangun ulang dengan Capgo Cloud Build). Setelah pengguna memperbarui biner, dependensi asli paket tersebut berurutan dan live update berjalan dengan benar.

Roll back jika paket tidak kompatibel sudah hidup

Jika paket tidak kompatibel sudah aktif di sebuah saluran, kembalikan saluran ke bangun yang paling kompatibel terakhir untuk menghentikan pelayanan hingga bangun asli keluar. Lihat Rollbacks.

Mencegah pengiriman tidak kompatibel

Dua pengawas komplementer, yang sebenarnya memeriksa paket asli Anda:

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

Tambahkan flag ke langkah Anda. Jika paket asli Anda tidak sesuai dengan versi yang hidup saat ini di saluran, unggah bundle upload Jika __CAPGO_KEEP_0__ tidak sesuai dengan __CAPGO_KEEP_1__, unggah terganggu dengan kode keluaran tidak nol dan tidak ada yang dikirim — jadi pipa Anda menghentikan Anda dari memublikan update OTA secara diam-diam yang tidak dapat berlaku sampai pengguna menginstal build asli:

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

Upload yang kompatibel — dan kasus-kasus di mana periksa tidak dapat dijalankan (saluran baru, atau tidak ada metadata remote) — melewati tanpa perubahan. Di terminal interaktif, ia menawarkan alur Builder native-build Capgo alih-alih; menolak gagal. (Tidak dapat dikombinasikan dengan --ignore-metadata-check.)

Trik

Saat Anda memiliki niat perlu bundle yang berbeda dari paket asli saluran (plugin baru, Capacitor upgrade, dan seterusnya), abaikan --fail-on-incompatible untuk upload dasar tersebut. Tahan flag pada CI OTA sehari-hari. Alur kerja saluran lengkap: Native + Saluran OTA Workflow.

Pengiriman melalui versi asli — metadata + --auto-min-update-version

Saat Anda Mengirimkan bangunan asli dan bundle bersamaan, letakkan saluran pada strategi dan unggah dengan metadata . __CAPGO_KEEP_0__ menjalankan periksa kompatibilitas pada setiap unggahan dan, ketika bundle memerlukan native __CAPGO_KEEP_1__ baru, meningkatkan lantai pembaruan sehingga perangkat yang belum menginstal bangunan asli yang sesuai tidak menerima: --auto-min-update-version. Capgo runs the compatibility check on every upload and, when a bundle needs new native code, raises the update floor so devices that haven’t installed the matching native build don’t receive it:

# 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

Aturan nomor versi seperti

ini --disable-auto-update major are tidak sebuah pengganti — mereka hanya menghalangi lonjakan versi dan tidak memeriksa kode native code, sehingga perubahan native yang dikirimkan dalam rilis minor atau patch masih keluar. Gunakan --fail-on-incompatible atau --auto-min-update-versionuntuk mendapatkan set lengkap opsi target.

Terkait Bagian berjudul “Terkait” Alur Kerja Native + OTA

Saluran dev/prod, kapan harus menjaga

untuk mendapatkan set lengkap opsi target.

untuk mendapatkan set lengkap opsi target. --fail-on-incompatibleuntuk mendapatkan set lengkap opsi target.

Auto OTA atau Native

Kabel bundle releaseType masuk ke GitHub Aksi atau GitLab sehingga CI memilih live update vs Capgo Bangun.

Target Versi

context

Jalankan hanya paket yang kompatibel menggunakan saluran, aturan semver, dan strategi metadata.

Rollback

Membalikkan saluran ke bangun yang kompatibel terakhir jika paket yang tidak kompatibel keluar.

Jenis Update

CLI: bundle

__CAPGO_KEEP_0__: paket

Referensi untuk kompatibilitas paket, releaseType, dan opsi unggah.

Jika Anda menggunakan Kompatibilitas Asli untuk menjaga live updates aman, hubungkannya dengan Target Versi context untuk mengarahkan bundle oleh versi asli, Rollbacks untuk kembali ketika bundle tidak kompatibel dikirimkan, Jenis Update Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ referensi bundle kompatibilitas dan releaseType perintah.