Konsistensi Asli

Aplikasi Anda akan digantikan oleh Capgo live update Bundle JavaScript langsung, tetapi tidak dapat mengubah 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 native-incompatible: Capgo masih dapat mengirimkannya, tetapi mungkin mengalami crash atau perilaku tidak terduga pada perangkat yang masih menjalankan versi native yang lebih lama.

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

Note

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.

TLDR: Perangkat Lunak Terupdate atau Nativ?

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 live update.

Pilih rilis aplikasi native ketika perubahan memperbarui capacitor.config.ts, pengaturan plugin yang disimpan di Capacitor konfigurasi, plugin native atau dependensi, Capacitor itu sendiri, atau file proyek iOS/Android. npx cap sync or npx cap copy before installed devices can use it, treat it as native.

Change	Mengirimkan dengan Capgo OTA?	Perubahan
HTML, CSS, JavaScript aplikasi web, gambar, font, dan aset pembangunan web lainnya	Mengapa	Mereka dimuatkan dari bundle web pada saat waktu eksekusi.
Perubahan paket JavaScript murni yang diintegrasikan 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 build.
Menambahkan, menghapus, atau mengupgrade Capacitor/plugin Cordova	Tidak	Binary native yang diinstal harus mengandung code yang sesuai.
Perubahan file proyek iOS atau Android	Tidak	Pengguna yang sudah ada memerlukan binary baru dari toko.

Plugin klien berdasarkan stack

Capgo mengirimkan klien pembarui yang spesifik untuk setiap runtime hybrid:

Plugin	Pilih 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 klien plugin — mereka membandingkan ketergantungan native yang direkam terhadap bundle dengan binary yang terinstal.

Mengapa kompatibilitas native penting

Setiap Capacitor aplikasi dikirim dalam dua lapisan:

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

Sebuah live update hanya mengganti lapisan JavaScript. Jika JavaScript baru tersebut memanggil plugin native atau API yang tidak dikompilasi ke dalam biner yang diinstal, panggilan 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 build native lama tidak dapat menjalankan bundle yang dibangun atas code native baru dengan aman.

Bagaimana Capgo mendeteksi konsistensi

Ketika 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 yang sedang berjalan di saluran:

• Jika mereka cocok, perubahan hanya JavaScript dan aman untuk dikirimkan melalui udara.
• Jika plugin ditambahkan, dihapus, atau versi dirubah, bundel akan native-incompatible — perubahan-perubahan itu hanya efektif setelah pengguna menginstal biner native baru.

Periksa dari CLI

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

Tabel CLI menampilkan setiap paket native beserta versi lokal, versi yang ada di channel, 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 (tersedia di log CI), dan --package-json / --node-modules untuk menunjuk ke jalur yang tepat dalam repositori monorepo.

Dapatkan hasil verifikasi mesin baca (CI)

Untuk pipeline 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

Jadwalkan pipa rilis Anda pada hal ini: kirimkan live update ketika mencetak OTAdan akan memicu pembangunan native ketika mencetak native.

Apa artinya pembaruan tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak not mencegah unggah — jika Anda mengunggah paket asli yang tidak kompatibel dan menetapkannya sebagai bangunan aktif saluran, Capgo akan mengirimkannya ke perangkat di saluran tersebut. (Anda dapat mengubah ini menjadi pintu keras dengan) --fail-on-incompatible — see Mencegah pengiriman tidak kompatibel di bawah.)

Pada perangkat yang masih menjalankan biner berusia lebih lama, maka kekurangan native code dapat menyebabkan aplikasi mengalami crash atau fitur rusak — meskipun update telah didownload dan diterapkan dengan sukses. Ini adalah mengapa live update dapat berjalan secara live dan disampaikan namun masih dapat merusak aplikasi bagi pengguna yang sudah ada, dan mengapa Capgo dapat memberi peringatan ketika bundle yang tidak kompatibel telah berjalan.

Capgo’s rollback otomatis Dapat menangkap kesalahan JavaScript yang dilempar sebelumnya notifyAppReady() berjalan, namun tidak dapat menggantikan pengiriman native code yang kompatibel — kesalahan yang menyebabkan aplikasi mengalami crash nanti, atau crash secara native, dapat melewati hal ini.

How to ship native changes safely

Publish perubahan native baru (solusi yang sebenarnya)

Jika sebuah bundle memerlukan native code yang baru, 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.

Kembali ke versi sebelumnya jika bundle yang tidak kompatibel sudah aktif

Jika sebuah bundle yang tidak kompatibel sudah aktif di sebuah saluran, kembalikan saluran ke versi terakhir yang kompatibel untuk menghentikan penyediaannya hingga build native keluar. Lihat Rollbacks.

Mencegah pengiriman yang tidak kompatibel

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

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

Tambahkan flag ke aplikasi Anda bundle upload Langkah 2. Jika paket native bundel tidak sesuai dengan versi yang sedang berjalan di channel, maka unggah Gagal dengan kode keluaran tidak nol dan tidak ada yang dikirimkan. — sehingga 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 di mana periksa tidak dapat dijalankan (saluran baru, atau metadata remote tidak ada) — melewati tanpa perubahan. Di terminal interaktif, ia menawarkan alur Capgo Pembangun build asli alih-alih; menolak gagal. (Tidak dapat dikombinasikan dengan --ignore-metadata-check.)

Trik

Ketika Anda memiliki niat perlu sebuah bundle yang berbeda dari paket native channel yang hidup (plugin baru, Capacitor pembaruan, dan seterusnya), lewati --fail-on-incompatible untuk upload dasar tersebut. Tahanlah flag setiap hari CI OTA. Alur kerja saluran lengkap: Saluran Asli + OTA Channel Workflow.

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

When Anda melakukan kirimlah bangunan asli dan paket bersamaan, letakkan saluran di metadata strategi dan unggah dengan --auto-min-update-version. Capgo menjalankan pengecekan kompatibilitas pada setiap unggahan dan, ketika bundel memerlukan native code baru, meningkatkan lantai update sehingga perangkat yang belum menginstal konstruksi asli 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 --disable-auto-update major tidak adalah sebagai pengganti — mereka hanya menghalangi lonjakan versi dan tidak memeriksa kode code asli, sehingga perubahan asli yang dikirimkan dalam rilis minor atau patch masih keluar. Gunakan --fail-on-incompatible atau --auto-min-update-versionuntuk set lengkap opsi target.

Lihat Versi Target untuk set lengkap opsi target.

Terkait

Alur Kerja Asli + OTA

Saluran pengembang/produksi, kapan untuk menjaga --fail-on-incompatible, dan bagaimana mengirimkan dasar asli native secara sengaja.

Auto OTA atau Asli

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

Target Versi

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

Rollbacks

Kembalikan saluran ke versi terakhir yang kompatibel jika paket tidak kompatibel yang telah diterbitkan.

Jenis Update

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

CLI: paket

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

Teruskan dari Kompatibilitas Nativ

Jika Anda menggunakan Kompatibilitas Asli untuk menjaga live update aman, hubungkannya dengan Target Versi untuk mengarahkan bundle berdasarkan versi asli, Rollback untuk kembali ketika bundle tidak kompatibel dikirimkan, Jenis Update untuk memahami versi saluran penghalang, dan Capgo CLI referensi bundle kompatibilitas dan releaseType untuk perintah kompatibilitas dan releaseType.