Capgo version_build vs version_name: Langkah Setup

Capgonama versinya mungkin terasa membingungkan di awal: version_build adalah baseline aplikasi native, sedangkan version_name melacak bundle di perangkat. Pahami perbedaannya agar Anda bisa mengecek alasan perangkat menerima atau tidak menerima update OTA sebelum melakukan rollout.

Kami menganalisis halaman troubleshooting dari 5 platform live-update, termasuk milik kami sendiri, dan menemukan dokumentasi kami mencantumkan 7 kode mismatch version_build, dibandingkan 5, 2, 2, dan 0 pada empat platform lainnya. Semakin banyak kode yang terdefinisi, semakin sedikit tebak-tebakan saat terjadi mismatch version_build.

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: Tes eligibility channel sebelum merilis update
• Langkah 6: Diagnosa 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 dari 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 menjadi acuan kelayakan update. Capgo membandingkan bundle yang ditugaskan ke sebuah channel dengan baseline native tersebut. Versi bundle yang terinstal di perangkat membantu mengidentifikasi code web saat ini, namun tidak menggantikan baseline native dalam aturan versi channel.

Cek perangkat di halaman Devices pada console Capgo dan catat kedua nilainya sebelum troubleshooting. Kemudian bandingkan dengan target bundle pada channel tersebut. Hal ini Aturan channel Capgo menjelaskan bagaimana target versi channel diperiksa terhadap version_build.

Pisahkan ketiga nilai ini dalam kolom berbeda di release note atau laporan tes. Jika tim hanya menulis satu “app version” secara umum, akan mudah salah membandingkan pasangan versi. Untuk pengecekan eligibility, 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 terus. 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 terbaru 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 ada di perangkat. Native baseline tetap terikat pada binary yang terinstal.

Perbedaan ini penting saat pengguna memiliki build app-store lama tetapi bundle web yang lebih baru. Bundle dapat berubah tanpa mengganti native binary, tetapi update OTA tidak bisa menambahkan native code yang tidak disertakan dalam aplikasi. Jika perubahan memerlukan plugin atau pengaturan native baru, rencanakan native build daripada menganggap upload bundle sebagai penggantinya.

Gunakan pengecekan cepat ini saat nilai terlihat tidak sinkron:

• Pastikan native binary mana yang terinstal di perangkat pengujian.
• Cari nilai versi yang diterima Capgo sebagai native baseline.
• Periksa versi bundle yang ditetapkan ke channel perangkat.
• Catat versi bundle yang terinstal secara terpisah dari keduanya.

Jangan menyimpulkan native baseline 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 di store bisa berbeda. Sumber yang benar adalah nilai yang benar-benar dikirim aplikasi Anda ke Capgo.

Setelah Anda bisa menamai 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

Agar andal version_build, cari versi native yang dilaporkan oleh aplikasi Capacitor Anda. Dokumentasi versi Capgo menjelaskan berbagai source key untuk iOS dan Android, lalu menggunakan nilai native tersebut sebagai baseline perbandingan OTA.

Di iOS

Cek CFBundleShortVersionString di dalam aplikasi Info.plist. Di kebanyakan proyek Xcode, key tersebut diatur ke $(MARKETING_VERSION), jadi nilai yang sebenarnya Anda edit adalah Marketing Version pada target tersebut. Verifikasi nilai di aplikasi yang sudah di-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 mungkin terlihat benar padahal binary yang terinstal melaporkan hal lain. Bandingkan versi di native app 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 tertukar dengan code Android atau versi package JavaScript yang tidak terkait. Untuk pengecekan ini, pertanyaan pentingnya adalah nama versi apa yang dikirim oleh aplikasi native tersebut.

Kebijakan versi yang selaras dapat membantu kedua platform tetap sinkron, tetapi jangan berasumsi keduanya sudah menggunakan satu sumber yang sama. iOS dan Android mungkin memiliki file, langkah build, atau jadwal rilis yang berbeda. Bandingkan nilai akhirnya saat pengecekan rilis, terutama jika salah satu platform memiliki jadwal rollout store yang berbeda.

Beberapa aplikasi mengatur versi native secara eksplisit di capacitor.config.ts melalui nilai version pada konfigurasi updater. Capgo Semver Tester mendefinisikan baseline native ini sebagai nilai yang bisa berasal dari konfigurasi atau metadata aplikasi native. Jika aplikasi Anda menimpa (override) metadata native, dokumentasikan pilihan tersebut agar tidak ada yang mengira versi store adalah sumber utamanya.

Untuk setiap platform, catat file sumber, nilai yang dihasilkan, dan build yang memuatnya. Ini akan memudahkan pelacakan jika terjadi ketidakcocokan setelah rilis, terutama 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 lama (stale file) dapat membuat review code terlihat selesai, padahal versi native yang dipaketkan tidak berubah.

Langkah 4: Atur dan verifikasi versi bundle yang diterima Capgo

Versi bundle mendeskripsikan update JavaScript, bukan binary native yang terinstal. Capgo bisa mengambil versi tersebut dari version field di package.json saat Anda tidak menyertakan versi bundle secara eksplisit. CLI --bundle bisa mengatur versi yang dikirim saat upload.

Pilih satu jalur dan buatlah jelas dalam proses rilis Anda. Jika package.json adalah sumbernya, naikkan field tersebut sebelum upload. Jika CI mengirimkan versi bundle melalui CLI, buat job tersebut mencetak versi yang terdeteksi di release log. Campuran kedua jalur secara diam-diam akan menyulitkan pelacakan mengapa channel menerima nilai tertentu.

Gunakan semantic versioning dalam format major.minor.patch yang umum, 1.2.3Strategi channel Capgo menggunakan bagian dari versi tersebut untuk menentukan apakah target bundle sesuai dengan baseline Native Build. Suffix pre-release seperti -beta.1 dapat membantu melabeli build khusus channel, namun pastikan versi tetap dapat di-parse dan konsisten di seluruh tool rilis Anda.

Pertimbangkan increment sebelum melakukan publish:

• Gunakan patch change untuk perbaikan web yang kompatibel dalam satu lini rilis 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.

Sebagai contoh, katakanlah aplikasi native yang terinstal melaporkan 1.2.3, sementara bundle saat ini adalah 1.2.4. Jika sebuah channel mengarah ke 1.2.5, bandingkan target tersebut dengan baseline native 1.2.3, bukan hanya terhadap bundle saat ini 1.2.4. Target yang diizinkan bergantung pada strategi update channel tersebut.

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 lini major atau minor baseline dapat diblokir. Periksa strategi yang dikonfigurasi daripada berasumsi setiap bundle yang terlihat lebih baru akan diterima.

Uji kombinasi tepat yang berencana Anda rilis:

1. Instal Native Build yang merepresentasikan target pengguna Anda.
2. Konfirmasi baseline native yang dikirim ke Capgo.
3. Assign perangkat pengujian ke channel yang dituju.
4. Cek target channel dan strategi versinya.
5. Minta update dan konfirmasi hasilnya di perangkat.

Jalankan pengecekan yang sama pada native baseline lain jika user base Anda menggunakan lebih dari satu versi store. Bundle yang jalan di fresh build mungkin terblokir di binary lama, dan itu bisa jadi aturan safety yang disengaja.

Untuk rilis yang lebih luas, mulai dengan test channel atau rollout terbatas. Pantau hasil eligibility yang tidak terduga sebelum memperluas audiens. Model channel Capgo memungkinkan tim mengarahkan bundle melalui release channel; pastikan target channel dan native line yang dituju jelas di release notes Anda.

Jika perangkat test tidak update, cek assignment channel dan nilai versinya sebelum upload lagi. Terus-menerus mempublish bundle yang sama tidak akan memperbaiki masalah baseline mismatch.

Langkah 6: Diagnosa mismatch versi dan buat rilis yang repeatable

Jika nilainya tidak sesuai ekspektasi, telusuri secara berurutan. Pertama, konfirmasi versi native app di perangkat. Lalu, cek apakah ada configuration override yang mengubah baseline. Selanjutnya, bandingkan bundle version yang diterima Capgo dengan target channel. Urutan ini memisahkan antara nilai source yang salah dengan aturan channel yang sudah berjalan sesuai setelan.

Penyebab umum termasuk bumping package.json sambil membiarkan versi native tetap sama, melakukan build satu platform dari release branch yang berbeda, dan mengetes perangkat yang terdaftar di channel lain. Kebingungan lainnya adalah menyebut semua angka sebagai “build version.” Catatlah mana nilai native, mana bundle yang di-upload, dan mana yang saat ini terinstal.

Untuk CI/CD, buat input versi menjadi eksplisit. Biarkan pipeline membaca versi rilis yang dituju dari sumber yang terkontrol, lalu teruskan ke perintah upload atau perbarui field package sebelum langkah upload. Catat native baseline dan target bundle yang telah ditentukan di output job. Hindari mengandalkan local state developer yang tidak bisa dilihat oleh build server.

Gunakan release gate yang akan gagal jika versi yang diperlukan hilang atau memiliki format yang tidak diterima tim Anda. Kemudian jalankan test upload ke channel yang benar sebelum promosi. Capgo mendukung alur deployment berbasis CLI, sehingga tim dapat memasukkan bundle upload ke dalam job CI/CD yang sudah ada dan tetap memiliki log perintah yang terlihat.

Don’t confuse these values with the Android WebView engine version. Our @capgo/capacitor-webview-version-checker plugin mengecek apakah engine WebView perangkat sudah usang dan dapat menampilkan native update prompt. Hal tersebut adalah pertanyaan terpisah dari version_build dan version_name, sehingga tidak akan menggantikan pengecekan native baseline dan target bundle pada channel tersebut.

Saat migrasi dari skema lama, jangan ubah semua nilai yang ada sekaligus. Petakan versi native lama ke native baseline terlebih dahulu. Kemudian, petakan web release yang di-upload ke bundle version. Uji build aplikasi yang ada terhadap strategi channel sebelum mengarahkannya ke pengguna.

Simpan catatan rilis singkat yang berisi source commit, native version, uploaded bundle version, channel, dan hasil tes. Jika rilis perlu dihentikan atau di-rollback, catatan tersebut membantu tim mengidentifikasi bundle mana yang dikirim ke mana. Ini juga membuat deployment berikutnya dapat diulang (repeatable) daripada bergantung pada ingatan seseorang tentang 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 current downloaded bundle version. Capgo menggunakan native baseline saat mengecek kelayakan target bundle pada sebuah channel. Pisahkan kedua nilai ini di logs dan release notes agar Anda bisa membedakan native app mana yang terinstal dan web bundle mana yang dimilikinya.

Apakah version_name mengontrol apakah update OTA diizinkan?

Tidak, strategi channel version pada Capgo membandingkan target bundle dengan version_build, yaitu native baseline. version_name mengidentifikasi current downloaded bundle. Jika perangkat tidak menerima update, periksa baseline, channel target, dan strategi yang dikonfigurasi sebelum mengubah nilai bundle saat ini.

Dari mana Capgo mendapatkan native version?

Pada iOS, Capgo membaca CFBundleShortVersionString, yang biasanya diisi oleh Xcode dari MARKETING_VERSION. Di Android, versi native berasal dari defaultConfig.versionName. Versi updater eksplisit di konfigurasi Capacitor dapat mengubah nilai yang dikirim aplikasi Anda, jadi pastikan kembali aplikasi yang sudah di-build.

Dari mana Capgo mendapatkan versi bundle?

Capgo dapat menggunakan field version pada package.json saat Anda tidak menyertakan versi bundle secara eksplisit. Anda juga dapat menyertakan versi tersebut bersama CLI --bundle milik Capgo. 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. Satu pengecekan ini dapat mendeteksi ketidakcocokan versi sebelum mencapai audiens yang lebih luas.