Kompatibilitas Native

A Capgo live update mengganti aplikasi Anda 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-incompatibleAplikasi Capgo masih dapat menyampaikan update, tetapi mungkin mengalami crash atau perilaku tidak terduga pada perangkat yang masih menjalankan versi native yang lebih lama.

Halaman ini menjelaskan bagaimana Capgo mendeteksi konsistensi native, apa artinya update yang tidak kompatibel bagi pengguna Anda, dan bagaimana mengirimkan perubahan native 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.

"langs:Catatan"

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.ts, konfigurasi 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 before installed devices can use it, treat it as native.

atau	Mengirimkan dengan Capgo OTA?	Perubahan
HTML, CSS, JavaScript aplikasi web, gambar, font, dan aset lainnya pembangunan web	Mengapa	Mereka dimuatkan dari bundle web pada saat runtime.
Perubahan paket JavaScript murni yang diintegrasikan ke dalam output web Anda	Mengapa	JavaScript yang dihasilkan adalah bagian dari bundle web.
capacitor.config.ts perubahan	Tidak	Capacitor konfigurasi dibaca ke dalam aplikasi native pada waktu build.
Menambahkan, menghapus, atau meningkatkan Capacitor/Cordova plugin	Tidak	Binary native yang diinstal harus mengandung code native 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 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 dikirim dalam dua lapisan:

• Lapisan 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.

Sebuah live update 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 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 dengan paket yang sedang berjalan di saluran:

• Jika mereka sesuai, perubahan tersebut hanya berupa JavaScript dan Aman dikirimkan secara nirkabel.
• Jika plugin ditambahkan, dihapus, atau versi berubah, bundel adalah native-incompatible — perubahan hanya berlaku 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

Trik

Add --text Mengganti emoji-emoji untuk OK/FAIL (tersedia dalam log CI), dan --package-json / --node-modules Mengarahkan ke jalur yang tepat dalam repositori monorepo.

Get a machine-readable verdict (CI)

Untuk pipeline bundle releaseType Mengurangi periksaan 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

Mengunci rilis pipa Anda dengan cara mengirimkan live update ketika mencetak OTAdan mengaktifkan pembangunan asli ketika mencetak native.

Apakah arti update yang tidak kompatibel bagi pengguna Anda

Peringatan

Dengan default, mendeteksi ketidakkompatibilitas tidak akan not mencegah unggah — jika Anda mengunggah bundle asli yang tidak kompatibel dan menetapkannya sebagai build aktif saluran, Capgo akan mengirimkannya ke perangkat di saluran tersebut. (Anda dapat mengubah ini menjadi pintu keras dengan) --fail-on-incompatible — see Hindari Pengiriman Tidak Kompatibel below.)

Pada perangkat yang masih menjalankan binary asli yang lebih tua, kemungkinan code yang hilang dapat menyebabkan aplikasi crash atau fitur rusak — bahkan meskipun update telah didownload dan diterapkan dengan sukses. Ini adalah mengapa live update dapat berjalan secara live dan diterima namun masih dapat merusak aplikasi untuk pengguna yang sudah ada, dan mengapa Capgo dapat memberi peringatan ketika bundle yang tidak kompatibel telah diterbitkan.

Capgo’s rollback otomatis bisa menangkap kesalahan JavaScript yang dilempar sebelum notifyAppReady() berjalan, namun ini bukanlah pengganti untuk mengirimkan code asli yang kompatibel — kesalahan yang menyebabkan aplikasi crash nanti, atau crash secara native, dapat melewati hal ini.

How to ship native changes safely

Publish perubahan binary native baru (solusi yang sebenarnya)

Ketika bundle membutuhkan code native yang baru, buat dan kirimkan binary baru ke App Store / Play Store (atau dengan menggunakan Capgo Cloud Build). Setelah pengguna memperbarui binary, ketergantungan native bundle akan berjalan dan live update akan berjalan dengan benar.

Roll back jika paket yang tidak kompatibel sudah aktif

If an incompatible bundle is already active on a channel, revert the channel to the last compatible build to stop serving it until the native build is out. See Rollbacks.

Hindari Pengiriman Tidak Kompatibel

Dua pengaman komplementer, yang keduanya memeriksa paket native Anda secara nyata:

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. Jika ada bundle yang tidak kompatibel sudah aktif, kembalikan channel ke versi terakhir yang kompatibel untuk menghentikan penyediaannya hingga versi native tersedia.

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 pembangunan native Capgo Builder; menolak gagal. (Tidak dapat digabungkan dengan --ignore-metadata-check.)

Trik

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

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

Ketika Anda melakukan mengirimkan build asli dan bundle bersamaan, menempatkan saluran pada strategi dan mengunggah dengan metadata strategi dan unggah dengan --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

Caution

Versi-nomor aturan seperti --disable-auto-update major bukan not 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 atau --auto-min-update-versionyang memeriksa paket native Anda.

Lihat Pemilihan Versi untuk set lengkap pilihan target.

Terkait

Alur Kerja Native + OTA

Saluran dev/prod, kapan untuk menjaga --fail-on-incompatible, dan bagaimana mengirimkan dasar native sengaja.

Auto OTA atau Native

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

Target Versi

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

Rollback

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

Jenis Update

Bagaimana cara aplikasi waktu, kondisi penundaan, dan penghalang versi bekerja sama.

CLI: paket

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

Teruskan dari Kompatibilitas Asli

Jika Anda menggunakan Kompatibilitas Natively Untuk menjaga live update aman, hubungkannya dengan Target Versi Untuk rutekan paket berdasarkan versi native, Rollbacks Mengembalikan ketika sebuah paket yang tidak kompatibel dikirimkan. Jenis Update Untuk memahami versi saluran yang diblokir, dan Capgo CLI referensi bundle __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ referensi bundle kompatibilitas