Kompatibilitas Native

Perbarui Capgo live update menggantikan bundel JavaScript aplikasi Anda. Pasang, sinkronkan, dan ikuti panduan sumber lengkap dari satu prompt yang dapat dicopy. secara instan, tetapi tidak dapat mengubah bagian asli dari aplikasi — plugin Cordova __CAPGO_KEEP_0__, dependensi native, dan konfigurasi proyek native yang dikompilasi ke dalam file biner yang diinstal. Ketika sebuah bundle baru memerlukan __CAPGO_KEEP_1__ native yang tidak dimiliki oleh file biner yang diinstal, maka bundle tersebut adalah 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 Halaman ini menjelaskan bagaimana __CAPGO_KEEP_0__ mendeteksi kompatibilitas native, apa artinya update yang tidak kompatibel bagi pengguna, 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_0__ dapat mengirimkan 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.

Capgo can send files from your generated web build folder. If the change only affects HTML, CSS, JavaScript, assets, or pure-JavaScript packages bundled into that output, ship it as a live update.

Gunakan rilis aplikasi native ketika perubahan memperbarui capacitor.config.tsKonfigurasi plugin disimpan di Capacitor konfigurasi, plugin native atau dependensi, Capacitor sendiri, atau file proyek iOS/Android. npx cap sync Cek yang praktis: jika perubahan harus memperbarui proyek native melalui npx cap copy atau

sebelum perangkat yang terinstal dapat menggunakannya, tundukkan sebagai native.	Ship with Capgo OTA?	Kirim dengan __CAPGO_KEEP_0__ OTA?
Mengapa	HTML, CSS, JavaScript aplikasi, gambar, font, dan aset pembangunan web lainnya	Ya
Mereka dimuat dari bundle web pada saat runtime.	Perubahan paket JavaScript murni-bundel ke dalam output web Anda	JavaScript yang dihasilkan adalah bagian dari bundle web.
capacitor.config.ts perubahan	Tidak	Konfigurasi Capacitor dibaca ke dalam aplikasi native pada saat build.
Mengambah, menghapus, atau mengupgrade Capacitor/Cordova plugin	Tidak	Aplikasi biner native yang diinstal harus berisi code yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada memerlukan aplikasi biner baru dari toko.

Plugin klien berdasarkan stack

Capgo mengirimkan klien pembaruan dedikasi 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

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

Mengapa kompatibilitas native penting

Setiap aplikasi Capacitor dikirim dalam dua lapisan:

• The biner native pengguna menginstal dari App Store / Play Store. Ini berisi Capacitor, plugin-plugin native Anda, dan konfigurasi native.
• The bundle JavaScript (aplikasi web Anda) yang Capgo dapat memperbarui secara nirkabel.

Perbaruan hidup hanya mengganti lapisan JavaScript. Jika JavaScript baru tersebut memanggil plugin native atau API yang tidak dikompilasi ke dalam biner yang terinstal, panggilan tersebut gagal pada waktu runtime — yang dapat menyebabkan aplikasi crash atau menghentikan fitur secara diam-diam. Dengan kata sederhana: Capgo tidak dapat memperbarui code native, sehingga perangkat yang menjalankan versi native lama tidak dapat menjalankan bundle yang dibangun atas code native baru.

Bagaimana Capgo mendeteksi kompatibilitas

Saat Anda mengunggah bundle — atau menjalankan cek secara manual — Capgo membandingkan paket 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 tersebut hanya JavaScript saja aman dikirimkan secara nirkabel.
• Jika plugin yang ditambahkan, dihapus, atau versi yang berubah, maka bundel adalah tidak kompatibel dengan native — perubahan hanya berlaku setelah pengguna menginstal biner native yang 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 menukar 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 keputusan yang dapat dibaca oleh mesin (CI)

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

Jadikan pipa rilis Anda bergantung pada ini: kirimkan pembaruan hidup ketika mencetak OTA, dan trigger build asli ketika mencetak native.

What artinya update tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak akan menghalangi 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.) bawah

Pada perangkat yang masih menjalankan biner asli yang lebih tua, keterlambatan native __CAPGO_KEEP_0__ dapat menyebabkan kacau atau fitur rusak — bahkan meskipun update yang diunduh dan diterapkan “berhasil.” Ini adalah mengapa update live dapat hidup dan disampaikan namun masih dapat mengganggu aplikasi bagi pengguna yang sudah ada, dan mengapa __CAPGO_KEEP_1__ dapat memberi peringatan ketika paket yang tidak kompatibel hidup., 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 dapat menangkap kesalahan JavaScript yang dilempar sebelum berjalan, tetapi tidak dapat menggantikan pengiriman native __CAPGO_KEEP_0__ yang kompatibel — kesalahan yang menyebabkan kacau kemudian, atau kacau secara native, dapat melewati. 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.

Judul bagian “Bagaimana mengirimkan perubahan native dengan aman”

Judul bagian “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.

Jika ada paket yang tidak kompatibel sudah aktif di saluran, kembalikan saluran ke versi terakhir yang kompatibel untuk menghentikan penyediaannya hingga versi native keluar. Lihat

Mencegah pengiriman yang tidak kompatibel Section titled “Mencegah pengiriman yang tidak kompatibel”.

Dua pengawas yang saling melengkapi, yang memang memeriksa paket native Anda:

Tambahkan flag ke

Jika paket native bundel tidak sesuai dengan versi yang sedang berjalan di saluran, maka pengunggahan --fail-on-incompatible

mengalami kegagalan dengan kode keluar yang tidak nol dan tidak ada yang dikirimkan — sehingga pipa Anda menghentikan Anda dari menyebarkan pembaruan OTA secara diam-diam yang tidak dapat berlaku hingga pengguna menginstal versi native: bundle upload Jika ada paket yang tidak kompatibel sudah aktif di saluran, kembalikan saluran ke versi terakhir yang kompatibel untuk menghentikan penyediaannya hingga versi native keluar. Lihat Rollbacks Mencegah pengiriman yang tidak kompatibel

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

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

Pengiriman pintu oleh versi native — metadata + --auto-min-update-version

Ketika Anda melakukan mengirimkan pembangunan native dan bundel bersama, letakkan saluran pada metadata strategi dan unggah dengan --auto-min-update-version. Capgo menjalankan periksa kompatibilitas pada setiap unggah dan, ketika bundel memerlukan native code baru, meningkatkan lantai update sehingga perangkat yang belum menginstal pembangunan native yang sesuai tidak menerima:

# 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

Hati-hati

Aturan versi seperti --disable-auto-update major tidak sebagai 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

Versi Targeting untuk set lengkap opsi target. Bab yang terkait berjudul “Related”

Bab yang terkait

Auto OTA atau Native

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

Versi Targeting

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

Rollbacks

Kembalikan saluran ke versi terakhir yang kompatibel jika paket tidak kompatibel yang berjalan.

Jenis Update

Bagaimana cara aplikasi waktu, kondisi delay, dan penghalang versi bekerja bersama.

CLI: paket

Referensi untuk kompatibilitas paket, jenis rilis, dan opsi unggah.

Lanjutkan dari Kompatibilitas Native

Jika Anda menggunakan Kompatibilitas Asli untuk menjaga pembaruan hidup aman, hubungkannya dengan Target Versi untuk mengarahkan bundle oleh versi native, Rollbacks untuk kembali ketika bundle tidak kompatibel dikirim, Jenis Pembaruan untuk memahami versi saluran penghalang, dan Capgo CLI referensi bundle kompatibilitas untuk perintah kompatibilitas dan releaseType.