Kompatibilitas Asli

A Capgo pembaruan live mengganti bundle JavaScript aplikasi Anda JavaScript bundle tetapi tidak dapat mengubah bagian native aplikasi — plugin Cordova __CAPGO_KEEP_0__, dependensi native, dan konfigurasi proyek native yang dikompilasi ke binary yang terpasang. Ketika bundle baru memerlukan __CAPGO_KEEP_1__ native yang tidak ada di binary yang terpasang, bundle tersebut adalah native-incompatible 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.

TLDR: 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 hidup.

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. Cek praktis: jika perubahan harus memperbarui proyek native melalui npx cap sync atau npx cap copy context

atau	Ship with Capgo OTA?	atau
context	atau	context
Paket JavaScript murni yang berubah-ubah diintegrasikan ke dalam keluaran web Anda	Ya	JavaScript yang dihasilkan merupakan bagian dari bundel web.
capacitor.config.ts perubahan	Tidak	Konfigurasi Capacitor dibaca ke dalam aplikasi native pada waktu build.
Mengambah, menghapus, atau mengupgrade plugin Capacitor/Cordova	Tidak	Binary native yang terpasang harus mengandung versi native code yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada memerlukan binary baru dari toko-toko.

Plugin klien oleh stack

Capgo mengirimkan klien pembaruan khusus untuk setiap runtime hybrid:

Plugin	Pakai 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 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 bineray native pengguna menginstal dari App Store / Play Store. Ini berisi Capacitor, plugin native Anda, dan konfigurasi native.
• Perangkat lunak JavaScript (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 yang tidak dikompilasi ke dalam biner yang terinstal, panggilan gagal pada waktu runtime — yang dapat menyebabkan aplikasi crash atau menghentikan 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.

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.

Judul bagian “Bagaimana Capgo mendeteksi konsistensi”

When you upload a bundle — or run the check manually — Capgo compares the dalam proyek lokal Anda (plugin Cordova Anda dan versi mereka) terhadap paket native yang direkam untuk bundle Capacitor Saat ini berada di saluran:

• Jika mereka cocok, perubahan hanya JavaScript dan aman untuk dikirimkan melalui udara.
• Jika plugin ditambahkan, dihapus, atau versi berubah, paket adalah tidak kompatibel dengan native — perubahan hanya berlaku setelah pengguna menginstal biner native baru.

Cek 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 (berguna dalam log CI), dan --package-json / --node-modules untuk menunjuk ke jalur yang tepat dalam repositori monorepo.

Terima keputusan yang dapat dibaca oleh mesin (CI)

Untuk pipeline bundle releaseType menggabungkan periksa ke dalam 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

Jalankan pipa rilis Anda pada 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 unggah 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 __CAPGO_KEEP_0__ 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 telah didownload dan diterapkan “berhasil.” Ini adalah mengapa update live dapat live dan disampaikan namun masih dapat menghancurkan aplikasi untuk pengguna yang sudah ada, dan mengapa Capgo dapat memberi peringatan ketika bundle yang tidak kompatibel telah live.

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 memerlukan code baru asli, buat dan kirimkan bangunan biner baru ke App Store / Play Store (atau bangun ulang dengan Capgo Cloud Build). Setelah pengguna memperbarui bangunan biner, dependensi asli paket akan berbaris dan pembaruan hidup berjalan dengan benar.

Roll back jika paket yang tidak kompatibel sudah hidup

Jika paket yang tidak kompatibel sudah aktif di saluran, kembalikan saluran ke bangunan kompatibel terakhir untuk menghentikan penyediaannya hingga bangunan asli keluar. Lihat Pengembalian.

Mencegah pengiriman tidak kompatibel

Dua pengawas yang saling melengkapi, yang sebenarnya memeriksa paket asli Anda:

Gagalkan 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, unggahannya akan bundle upload __CAPGO_KEEP_0__ terganggu dengan kode keluaran tidak nol dan tidak ada yang dikirimkan — jadi pipa Anda menghentikan Anda dari menerbitkan pembaruan 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 Capgo Pembangun native-build sebaliknya; 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), lewati --fail-on-incompatible untuk upload dasar tersebut. Tahanlah flag setiap hari CI OTA. Alur saluran lengkap: Saluran Asli + OTA Channel Workflow.

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

Saat Anda melakukan mengirimkan build asli dan bundle bersamaan, atur saluran pada strategi dan unggah dengan metadata . __CAPGO_KEEP_0__ menjalankan pengecekan kompatibilitas pada setiap unggahan dan, ketika bundle memerlukan native __CAPGO_KEEP_1__ yang baru, meningkatkan lantai pembaruan sehingga perangkat yang belum menginstal build asli yang sesuai tidak menerima pembaruan tersebut: --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

adalah --disable-auto-update major are bukan substitusi — 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 yang terkait Arus Kerja Native + OTA

Saluran pengembang/produksi, kapan harus mempertahankan

Versi Targeting

untuk mendapatkan set lengkap opsi target. --fail-on-incompatibleBagian yang terkait

Auto OTA atau Native

Wire bundle releaseType ke dalam GitHub Aksi atau GitLab sehingga CI memilih pembaruan hidup vs Capgo Bangun.

Target Versi

context

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

Rollback

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

Jenis Pembaruan

CLI: bundle

__CAPGO_KEEP_0__: paket

Referensi untuk kompatibilitas paket, releaseType, dan opsi unggah.

Jika Anda menggunakan Kompatibilitas Asli untuk menjaga pembaruan hidup aman, hubungkannya dengan Target Versi context: Halaman/area: Halaman pemasaran solusi Capgo. Peran: Judul bagian atau halaman. Dilihat di: halaman solusi/target-versi.astro. Kunci pesan `solutions_version_targeting_title` (Judul Target Versi Solusi). | Halaman/area: Halaman pemasaran solusi Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman solusi/target-versi.astro. Kunci pesan `solutions_version_targeting` (Target Versi Solusi). untuk mengarahkan bundle oleh versi asli, Rollback untuk kembali ketika bundle tidak kompatibel dikirim, Jenis Pembaruan Capgo CLI bundle reference Referensi Bundle __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ untuk kompatibilitas dan perintah releaseType.