Kemampuan Kompabilitas Asli

Pembaruan Hidup Capgo mengganti bundel aplikasi Anda secara instan, tetapi tidak dapat mengubah bagian asli aplikasi Anda — plugin Cordova Capgo, dependensi asli, dan konfigurasi proyek asli yang dikompilasi ke dalam file biner yang diinstal. Ketika bundel baru memerlukan __CAPGO_KEEP_1__ asli yang tidak ada di file biner yang diinstal, bundel tersebut adalah tidak kompatibel dengan asli. : __CAPGO_KEEP_0__ masih dapat mengirimkannya, tetapi mungkin mengalami kegagalan atau perilaku tidak terduga pada perangkat yang masih menjalankan versi asli yang lebih lama. Sync Source guide 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 Ready to paste: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

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

Catatan

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

Mengapa kompatibilitas native penting

Setiap aplikasi Capacitor dikirim dalam dua lapisan:

• Lapisan biner native pengguna menginstal dari App Store / Play Store. Lapisan ini berisi Capacitor, plugin native Anda, dan konfigurasi native.
• Lapisan bundle JavaScript (your web app) that Capgo can update over the air.

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.

How Capgo detects compatibility

Bab berjudul “Bagaimana Capgo mendeteksi konsistensi”. Saat Anda mengunggah bundle — atau menjalankan cek secara manual — __CAPGO_KEEP_0__ membandingkan in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle dalam proyek lokal Anda (plugin Cordova Anda dan versi mereka) terhadap plugin native yang direkam untuk bundle:

• saat ini berada di saluran Jika mereka sesuai, perubahan tersebut hanya JavaScript dan.
• aman untuk dikirimkan secara nirkabel Jika plugin ditambahkan, dihapus, atau versi berubah, bundle tersebut adalah tidak kompatibel dengan native — perubahan-perubahan tersebut hanya efektif setelah pengguna menginstal biner 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 di dalam repositori monorepo.

Dapatkan keputusan yang dapat dibaca oleh mesin (CI)

Untuk pipa, bundle releaseType menggabungkan periksa ke dalam kata tunggal:

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

Tutup pipa rilis Anda dengan ini: kirimkan pembaruan hidup ketika mencetak OTAdan trigger build asli ketika mencetak native.

Apa artinya pembaruan yang tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak menghambat unggah — jika Anda mengunggah bundle native 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 tersebut. (Anda dapat mengubah ini menjadi pintu keras dengan — lihat --fail-on-incompatible Mencegah pengiriman tidak kompatibel di bawah.) Pada perangkat yang masih menjalankan binary native yang lebih tua

, komponen native __CAPGO_KEEP_0__ yang hilang dapat menyebabkan kacau atau fitur rusak — meskipun update yang diunduh dan diterapkan “berhasil.” Ini adalah mengapa update hidup dapat hidup dan dikirimkan namun masih dapat menghancurkan aplikasi untuk pengguna yang ada, dan mengapa __CAPGO_KEEP_1__ dapat memberi peringatan Anda ketika bundle tidak kompatibel keluar. Mengapa Inkompatibilitas Dapat Menghancurkan Aplikasi Anda, 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 dapat menangkap kesalahan JavaScript yang dilempar sebelum notifyAppReady() berjalan, tetapi itu tidak merupakan pengganti untuk mengirimkan kode native yang kompatibel code — kesalahan yang menghancurkan nanti, atau menghancurkan secara native, dapat melewati itu.

Bagaimana mengirimkan perubahan native dengan aman

Publikasikan build native baru (solusi yang sebenarnya)

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

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

Bagaimana mengirimkan perubahan native dengan aman Rollbacks.

Mencegah pengiriman tidak kompatibel

Dua pengawas komplementer, keduanya memeriksa sebenarnya 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 channel, unggahan bundle upload mengalami kegagalan dengan kode keluaran tidak nol dan tidak ada yang dikirimkan — sehingga pipa Anda mencegah Anda menerbitkan pembaruan OTA diam-diam yang tidak dapat berlaku sampai pengguna menginstal build native: Jendela terminal

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.)

Mengirimkan pengiriman oleh versi asli — metadata + --auto-min-update-version

Ketika Anda melakukan mengirimkan build asli dan bundle bersamaan, masukkan 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 update sehingga perangkat yang belum menginstal build asli yang sesuai tidak menerima update 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 pengganti — mereka hanya menghalangi lonjakan versi dan tidak memeriksa __CAPGO_KEEP_0__ asli, sehingga perubahan asli yang dikirimkan dalam rilis minor atau patch masih keluar. Gunakan a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible , yang memeriksa paket native Anda. --auto-min-update-versionLihat

Target Versi untuk set lengkap opsi target. Bagian yang terkait

Judul bagian “Related”

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

Rollbacks

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

Jika sebuah bundle tidak kompatibel, maka kembalikan saluran ke versi terakhir yang kompatibel.

Jenis Update

Bagaimana cara mengatur waktu, kondisi delay, dan penghalang versi bekerja bersama-sama.

CLI: bundle

Referensi untuk kompatibilitas bundle, releaseType, dan opsi unggah.

Lanjutkan dari Kompatibilitas Asli

Kompatibilitas Asli untuk menjaga pembaruan hidup aman, hubungkannya dengan Pengaturan Versi untuk mengarahkan bundle berdasarkan versi asli, Jika Anda menggunakan Kompatibilitas Asli untuk menjaga pembaruan hidup aman, hubungkannya dengan Pengaturan Versi untuk mengarahkan bundle berdasarkan versi asli, Pengembalian 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.