Capgonama versi-nya bisa terasa membingungkan di awal: version_build adalah native app baseline, sedangkan version_name melacak bundle di perangkat. Pahami perbedaannya dengan benar, dan Anda bisa memeriksa mengapa suatu perangkat akan atau tidak akan menerima pembaruan OTA sebelum dirilis.
Kami menganalisis halaman troubleshooting dari 5 platform live-update, termasuk milik kami sendiri, dan menemukan bahwa dokumentasi kami mencantumkan 7 kode mismatch version_build yang bernama, dibandingkan 5, 2, 2, dan 0 untuk empat lainnya. Semakin banyak kode bernama, semakin sedikit tebakan saat mismatch version_build muncul.
Table of Contents
- Langkah 1: Temukan version_build dan version_name di Capgo
- Langkah 2: Identifikasi native baseline dan bundle yang diunduh
- Langkah 3: Cek asal versi native app Anda
- Langkah 4: Atur dan verifikasi versi bundle yang diterima Capgo
- Langkah 5: Uji kelayakan channel sebelum merilis update
- Langkah 6: Diagnosis mismatch versi dan buat rilis yang repeatable
- FAQ
- Kesimpulan
Langkah 1: Temukan version_build dan version_name di Capgo
Mulailah dengan menganggap keduanya sebagai dua fakta berbeda tentang satu instalasi app. version_build memberitahu Capgo versi native app mana yang ada di perangkat. version_name memberitahu Capgo JavaScript bundle mana yang sudah diunduh perangkat. Nilainya bisa berbeda, dan hal itu sering kali memang diharapkan.
Dalam model versi Capgo, versi native adalah titik acuan untuk kelayakan update. Capgo membandingkan bundle yang ditugaskan ke sebuah channel dengan baseline native tersebut. Versi bundle yang terpasang di perangkat membantu mengidentifikasi code web saat ini, tetapi tidak menggantikan baseline native dalam aturan versi channel.
Cari perangkat di halaman Devices pada konsol Capgo dan catat kedua nilai tersebut sebelum troubleshooting. Lalu bandingkan dengan target bundle channel. The Aturan channel Capgo menjelaskan bagaimana versi target channel diperiksa terhadap version_build.
| Nilai | Apa yang diwakilinya | Gunakan untuk menjawab | Sumber umum |
|---|---|---|---|
version_build |
Baseline aplikasi native yang dikirim ke Capgo | Apakah native app ini dapat menerima target bundle dari channel tersebut? | Versi native app, atau nilai konfigurasi Capacitor yang eksplisit |
version_name |
Bundle JavaScript yang saat ini diunduh | Versi bundle mana yang terinstal sekarang? | Versi bundle yang ditentukan saat upload |
| Target channel | Bundle yang ditetapkan ke channel perangkat | Versi mana yang sedang dicek Capgo untuk update? | Penetapan channel saat ini |
Simpan ketiga nilai di kolom terpisah dalam release note atau laporan tes. Jika tim hanya menulis satu “app version” generik, pasangan versi yang dibandingkan mudah keliru. Untuk kelayakan update, bandingkan target bundle dengan version_build. Untuk web code yang terinstal, cek version_name.
Penamaan Capgo mungkin terlihat berbeda dari konvensi Android, di mana tim sering menggunakan “build” untuk nomor build yang naik. Di sini, baca field berdasarkan peran Capgo-nya, bukan berdasarkan namanya. Kebiasaan kecil ini mencegah banyak kebingungan saat rilis.
Langkah 2: Identifikasi native baseline dan bundle yang diunduh
Sebelum mengubah nilai versi, identifikasi code mana yang bersifat native dan code mana yang dikirim sebagai bundle. Native app adalah binary iOS atau Android yang terinstal. Bundle berisi aset web yang bisa diterima aplikasi Capacitor melalui OTA update.
Bayangkan sebuah native app yang dirilis dengan baseline 1.2.3. Perbaikan web berikutnya diunggah sebagai bundle 1.2.4. Capgo memeriksa apakah target bundle channel diizinkan untuk native baseline 1.2.3. Jika memenuhi syarat, perangkat dapat mengunduh bundle tersebut. Setelah instalasi, version_name mencerminkan bundle yang sekarang ada di perangkat. Native baseline tetap terikat pada binary yang terinstal.
Perbedaan ini penting ketika pengguna memiliki build App Store yang lebih lama tetapi bundle web yang lebih baru. Bundle dapat berubah tanpa mengganti binary native, tetapi update OTA tidak dapat menambahkan code native yang tidak disertakan dalam aplikasi. Jika perubahan membutuhkan plugin atau pengaturan native baru, rencanakan native build, bukan menganggap upload bundle sebagai pengganti.

Gunakan cek cepat ini saat nilai terlihat tidak sinkron:
- Pastikan binary native mana yang terinstal di perangkat pengujian.
- Cari nilai versi yang diterima Capgo sebagai baseline native.
- Periksa versi bundle yang ditugaskan ke channel perangkat.
- Catat versi bundle yang terpasang secara terpisah dari keduanya.
Jangan menyimpulkan baseline native dari package.json kecuali jika proses build Anda sengaja menyalin nilai tersebut ke versi native atau konfigurasi Capgo. Versi proyek JavaScript dan versi aplikasi yang terinstal dari store bisa berbeda. Sumber yang benar adalah nilai yang benar-benar dikirim oleh aplikasi Anda ke Capgo.
Setelah Anda bisa menentukan baseline dan bundle saat ini, tugas berikutnya adalah melacak setiap nilai kembali ke file sumbernya. Di sinilah perbedaan antar platform biasanya muncul.
Langkah 3: Cek asal versi native app Anda
Untuk hasil yang andal version_build, cari versi native yang dilaporkan oleh aplikasi Capacitor Anda. Dokumentasi versi Capgo menjelaskan kunci sumber yang berbeda untuk iOS dan Android, lalu menggunakan nilai native yang dihasilkan sebagai baseline perbandingan OTA.
Di iOS
Periksa CFBundleShortVersionString di dalam aplikasi Info.plist. Di sebagian besar proyek Xcode, key tersebut diatur ke $(MARKETING_VERSION), jadi nilai yang sebenarnya Anda edit adalah Marketing Version pada target tersebut. Verifikasi nilai di aplikasi hasil build, bukan hanya di template atau file yang mungkin ditimpa oleh proses build Anda.
Saat tim memperbarui proyek Xcode tetapi tidak memperbarui nilai yang sampai ke aplikasi, tampilan proyek lokal bisa terlihat benar padahal binary yang terinstal melaporkan hal lain. Bandingkan versi di aplikasi native yang dihasilkan dengan nilai yang diharapkan oleh proses release Anda.
Di Android
Periksa defaultConfig.versionName di konfigurasi Gradle aplikasi Android. Nama versi native tersebut digunakan dalam perbandingan OTA Capgo. Jangan mencampuradukkannya dengan code build Android atau versi paket JavaScript yang tidak terkait. Untuk pengecekan ini, pertanyaan pentingnya adalah nama versi apa yang dikirim oleh aplikasi native.
Kebijakan versi bersama dapat membantu kedua platform tetap selaras, tetapi jangan asumsikan mereka sudah berbagi satu sumber. iOS dan Android mungkin memiliki file, langkah build, atau waktu rilis yang terpisah. Bandingkan nilai akhir mereka selama pengecekan rilis, terutama jika satu platform memiliki jadwal rollout store yang berbeda.
Beberapa aplikasi secara eksplisit mengatur versi native di capacitor.config.ts melalui nilai version pada konfigurasi updater. The Capgo Semver Tester mendeskripsikan baseline native ini sebagai nilai yang bisa berasal dari konfigurasi atau metadata aplikasi native. Jika aplikasi Anda menimpa metadata native, dokumentasikan pilihan tersebut agar tidak ada yang mengasumsikan versi store sebagai sumbernya.
Untuk setiap platform, catat file sumber, nilai hasil resolve, dan build yang memuatnya. Ini memudahkan pelacakan jika terjadi ketidakcocokan setelah rilis, saat repositori mungkin sudah berisi versi yang lebih baru daripada aplikasi yang terinstal di perangkat tester.
Hanya ubah sumber yang benar-benar dibaca oleh build Anda. Mengedit file usang bisa membuat review code terlihat selesai, padahal versi native yang dikemas tidak berubah.
Langkah 4: Atur dan verifikasi versi bundle yang diterima Capgo
Versi bundle mendeskripsikan update JavaScript, bukan binary native yang terinstal. Capgo dapat mengambil versi tersebut dari version di package.json saat Anda tidak memberikan versi bundle secara eksplisit. Opsi CLI --bundle dapat mengatur versi yang dikirim saat upload.
Pilih satu jalur dan perjelas dalam proses rilis Anda. Jika package.json adalah sumbernya, naikkan field itu sebelum upload. Jika CI meneruskan versi bundle melalui CLI, buat job mencetak versi hasil resolve di release log. Campuran diam-diam dari kedua jalur membuat lebih sulit mengetahui mengapa channel menerima nilai tertentu.
Gunakan semantic versioning dalam format major.minor.patch yang umum, seperti 1.2.3. Strategi channel Capgo menggunakan bagian dari versi tersebut untuk menentukan apakah target bundle cocok dengan baseline native. Suffix pre-release seperti -beta.1 bisa membantu memberi label build khusus channel, tetapi pastikan versi tetap dapat di-parse dan konsisten di seluruh tools rilis Anda.
Pikirkan increment sebelum publish:
- Gunakan patch change untuk perbaikan web yang kompatibel dalam release line yang sama.
- Gunakan perubahan minor jika perubahan tersebut termasuk dalam lini fitur baru yang kompatibel.
- Gunakan perubahan major jika batas kompatibilitas berubah dan code native lama mungkin tidak mendukung bundle tersebut.
Label tersebut adalah konvensi tim, bukan cara menambah kapabilitas native lewat OTA. Nomor versi tidak bisa membuktikan bahwa sebuah bundle aman untuk aplikasi native. Pastikan keputusan kompatibilitas tetap mengacu pada code dan dependensi di dalam binary.
Sebelum upload, bandingkan versi package atau nilai CLI dengan versi yang muncul pada bundle setelah upload. Periksa juga channel yang akan menyajikannya. Mengupload bundle dengan nama yang benar ke channel yang salah tetap bisa menyebabkan hasil pengujian yang keliru.
String yang tidak valid atau tidak konsisten harus dicek dulu, jangan ditebak. Simpan nilai rilis yang sudah terbukti aman, perbaiki sumbernya, dan uji versi hasil resolve sebelum dipromosikan.
Panduan Referensi perintah Capgo CLI sangat berguna saat Anda menghubungkan proses upload ke dalam sebuah script, karena versi bundle merupakan bagian dari input perintah release.
Langkah 5: Uji kelayakan channel sebelum merilis update
Kelayakan channel adalah hasil perbandingan, bukan tebakan berdasarkan bundle mana yang terlihat lebih baru. Capgo memeriksa bundle target channel terhadap baseline native yang dikirim sebagai version_build. Bundle yang sedang di-download, yang dilaporkan sebagai version_name, bukan baseline untuk aturan channel tersebut.
Misalnya, katakanlah aplikasi native yang terinstal melaporkan 1.2.3, sedangkan bundle saat ini adalah 1.2.4. Jika channel menunjuk ke 1.2.5, evaluasi target terhadap baseline native 1.2.3, bukan hanya terhadap bundle saat ini 1.2.4. Target mana yang diizinkan bergantung pada strategi update channel.
Capgo mendokumentasikan strategi seperti major dan minor yang membatasi update terhadap baseline native. Dengan strategi major, target dengan versi major yang lebih tinggi dapat diblokir. Dengan strategi minor, target yang mengubah garis major atau minor baseline dapat diblokir. Periksa strategi yang dikonfigurasi, jangan berasumsi bahwa setiap bundle yang terlihat lebih baru akan diterima.

Uji kombinasi persis yang Anda rencanakan untuk dirilis:
- Instal native build yang mewakili pengguna yang Anda targetkan.
- Konfirmasi baseline native yang dikirim ke Capgo.
- Tugaskan perangkat uji ke channel yang dimaksud.
- Periksa target channel dan strategi versinya.
- Minta update dan konfirmasi hasil pada perangkat.
Jalankan pemeriksaan yang sama pada baseline native lain jika basis pengguna Anda memiliki lebih dari satu versi store yang digunakan. Bundle yang berfungsi untuk build baru mungkin diblokir untuk binary yang lebih lama, dan itu mungkin merupakan aturan keamanan yang dimaksudkan.
Untuk rilis yang lebih luas, mulai dengan channel uji atau rollout terbatas. Perhatikan hasil kelayakan yang tidak terduga sebelum memperluas audiens. Model channel Capgo memungkinkan tim mengarahkan bundle melalui channel rilis; pastikan target dan garis native yang dimaksud untuk setiap channel jelas dalam catatan rilis Anda.
Jika perangkat uji tidak ter-update, periksa penugasan channel dan nilai versinya sebelum mengunggah ulang. Menerbitkan bundle yang sama berulang kali tidak akan memperbaiki ketidakcocokan baseline.
Langkah 6: Diagnosis mismatch versi dan buat rilis yang repeatable
Jika nilai tidak sesuai harapan, telusuri secara berurutan. Pertama, pastikan versi aplikasi native di perangkat. Lalu periksa apakah ada override konfigurasi yang mengubah baseline. Selanjutnya, bandingkan versi bundle yang diterima Capgo dengan target channel. Urutan ini memisahkan nilai sumber yang salah dari aturan channel yang berjalan sesuai pengaturan.
Penyebab umum termasuk bumping package.json sambil membiarkan versi native tidak berubah, mem-build satu platform dari branch rilis berbeda, dan menguji perangkat yang ditetapkan ke channel lain. Sumber kebingungan lain adalah menyebut setiap angka sebagai “build version.” Catat nilai mana yang native, mana bundle yang di-upload, dan mana yang sedang terpasang.
Untuk CI/CD, buat input versi eksplisit. Biarkan pipeline membaca versi rilis yang dimaksud dari sumber terkontrol, lalu teruskan ke perintah upload atau perbarui field package sebelum langkah upload. Catat native baseline dan target bundle yang sudah ditetapkan di output job. Hindari mengandalkan state lokal developer yang tidak bisa dilihat build server.
Gunakan release gate yang gagal jika versi yang diperlukan hilang atau formatnya tidak diterima tim Anda. Kemudian jalankan test upload ke channel yang benar sebelum promosi. Capgo mendukung alur deployment berbasis CLI, sehingga tim dapat memasukkan upload bundle ke job CI/CD yang sudah ada dan tetap punya log perintah yang terlihat.
Jangan samakan nilai-nilai ini dengan versi engine Android WebView. Plugin kami @capgo/capacitor-webview-version-checker memeriksa apakah engine WebView perangkat sudah usang dan dapat menampilkan prompt update native. version_build dan version_name, sehingga tidak pernah menggantikan pengecekan native baseline dan target bundle pada channel tersebut.
Saat migrasi dari skema lama, jangan ganti nama semua nilai yang ada dalam satu langkah. Petakan versi native lama ke native baseline dulu. Lalu petakan web release yang di-upload ke bundle version. Uji build aplikasi yang ada terhadap strategi channel sebelum mengarahkan pengguna ke sana.
Simpan catatan rilis singkat berisi source commit, native version, bundle version yang di-upload, channel, dan hasil tes. Jika rilis perlu dijeda atau di-rollback, catatan itu membantu tim mengetahui bundle mana yang dikirim ke mana. Ini juga membuat deployment berikutnya bisa diulang, bukan bergantung pada ingatan seseorang soal file mana yang diubah.
FAQ
Apa perbedaan antara version_build dan version_name di Capgo?
version_build adalah native app baseline, sedangkan version_name adalah bundle version yang saat ini ter-download. Capgo memakai native baseline saat mengecek kelayakan target bundle sebuah channel. Pisahkan kedua nilai ini di logs dan release notes agar Anda tahu native app mana yang terinstal dan web bundle mana yang dipakainya.
Apakah version_name mengontrol apakah update OTA diizinkan?
Tidak, strategi channel version di Capgo membandingkan target bundle dengan version_build, yaitu native baseline. version_name mengidentifikasi bundle yang saat ini ter-download. Jika perangkat tidak menerima update, periksa baseline, target channel, dan strategi yang dikonfigurasi sebelum mengubah nilai bundle saat ini.
Dari mana Capgo mendapatkan native version?
Di iOS, Capgo membaca CFBundleShortVersionString, yang biasanya diisi Xcode dari MARKETING_VERSION. Di Android, versi native berasal dari defaultConfig.versionName. Versi updater eksplisit dalam konfigurasi Capacitor dapat mengubah nilai yang dikirim aplikasi Anda, jadi verifikasi aplikasi yang sudah di-build.
Dari mana Capgo mendapatkan versi bundle?
Capgo dapat menggunakan field version di package.json saat Anda tidak menyertakan versi bundle secara eksplisit. Anda juga bisa menentukan versi melalui opsi milik CLI --bundle Pilih satu sumber yang jelas untuk workflow rilis Anda, lalu verifikasi versi yang diterima Capgo setelah upload.
Kesimpulan
Gunakan version_build untuk baseline native dan version_name untuk bundle yang terinstal. Sebelum rollout berikutnya, verifikasi kedua nilai tersebut di perangkat uji dan bandingkan target channel dengan baseline. Pengecekan itu saja bisa mendeteksi ketidakcocokan versi sebelum menjangkau audiens yang lebih luas.