Ke halaman utama

Pengaturan Versi

Panduan ini menjelaskan cara mengirimkan bundle terbaru yang kompatibel secara otomatis kepada pengguna berdasarkan versi aplikasi native mereka, seperti pendekatan Ionic AppFlow. Ini memastikan manajemen update yang sederhana dan peluncuran yang lebih cepat sambil mencegah masalah kompatibilitas.

Capgo’s version targeting system allows you to:

  • Automatis mengirimkan pembaruan yang kompatibel kepada pengguna berdasarkan versi aplikasi aslinya
  • Mencegah perubahan yang mengganggu agar tidak mencapai versi aplikasi yang tidak kompatibel
  • Menangani beberapa versi aplikasi secara bersamaan tanpa logika kompleks
  • Melakukan pembaruan yang halus kepada segmen pengguna tertentu

Mengapa Targeting Versi Penting (Terutama bagi Pengguna AppFlow)

Judul bagian “Mengapa Targeting Versi Penting (Terutama bagi Pengguna AppFlow)”

Jika Anda sudah familiar dengan Ionic AppFlow, Anda tahu betapa kritisnya untuk memastikan pengguna hanya menerima pembaruan yang kompatibel. AppFlow secara otomatis memasangkan paket pembaruan live ke versi aplikasi asli, mencegah kode JavaScript yang tidak kompatibel disampaikan ke aplikasi asli code yang lebih tua.

Capgo menyediakan jaminan keamanan yang sama, dengan fitur tambahan:

  • Kontrol yang lebih halus atas matching versi
  • Strategi yang lebih dari satu (saluran, semver, konstrain native)
  • Keterlihatan yang lebih baik atas distribusi versi
  • API dan CLI mengontrol bersama dengan pengelolaan dashboard

Metode ini sangat berguna ketika:

  • Anda memiliki pengguna pada versi mayor yang berbeda dari aplikasi Anda (misalnya, v1.x, v2.x, v3.x)
  • Anda perlu menjaga konsistensi ke belakang saat mengeluarkan perubahan yang mengganggu
  • Anda ingin mencegah bundle yang lebih baru mengganggu native code yang lebih tua
  • Anda sedang melakukan migrasi pengguna secara bertahap dari satu versi ke versi lain
  • Anda sedang melakukan migrasi dari AppFlow dan ingin menjaga keamanan pembaruan yang sama

How It Bekerja

Bagaimana Cara Kerja

Capgo menggunakan pendekatan multi-layered untuk mencocokkan pengguna dengan pembaruan yang kompatibel:

  1. Keterbatasan Versi Nativ: Mencegah bundle dari dikirimkan ke versi native yang tidak kompatibel
  2. Pengaturan Rute Berdasarkan Saluran: Mengarahkan versi aplikasi yang berbeda ke saluran pembaruan yang berbeda
  3. Pengendalian Versi Semantik: Mengblokir otomatis pembaruan di batas major/minor/patch
  4. Penyesuaian Tingkat Perangkat: Mengarahkan perangkat atau kelompok pengguna tertentu
graph TD
A[User Opens App] --> B{Check Device Override}
B -->|Override Set| C[Use Override Channel]
B -->|No Override| D{Check local plugin channel}
D -->|setChannel value| E[Use local setChannel channel]
D -->|No local channel| F{Check defaultChannel in App}
F -->|Has defaultChannel| G[Use App's defaultChannel]
F -->|No defaultChannel| H[Use Cloud Default Channel]
C --> I{Check Version Constraints}
E --> I
G --> I
H --> I
I -->|Compatible| J[Deliver Update]
I -->|Incompatible| K[Skip Update]

Strategi 1: Rute Versi Berdasarkan Saluran

Bab berjudul “Strategi 1: Rute Versi Berdasarkan Saluran”

Ini adalah pendekatan yang disarankan untuk mengelola perubahan yang memecah dan pembaruan versi utama. Ini mirip dengan model pengiriman AppFlow.

  • Aplikasi v1.x (100.000 pengguna) → production saluran
  • Aplikasi v2.x (50.000 pengguna dengan perubahan yang mengganggu) → v2 saluran
  • Aplikasi v3.x (10.000 pengguna beta) → v3 saluran

Langkah 1: Konfigurasi Saluran untuk Setiap Versi Utama

Bagian berjudul “Langkah 1: Konfigurasi Saluran untuk Setiap Versi Utama”
// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production', // or omit for default
}
}
};
export default config;
// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // Routes v2 users automatically
}
}
};
// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v3', // Routes v3 users automatically
}
}
};
Jendela terminal
# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3
# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign
Jendela terminal
# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production
# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2
# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3
  • Zero code changes - Routing saluran terjadi secara otomatis
  • Pemisahan yang jelas - Setiap versi memiliki jalur pembaruan sendiri
  • Pengaturan yang fleksibel - Kirim pembaruan ke kelompok versi tertentu
  • Peluncuran yang aman - Perubahan yang memecah tidak pernah mencapai versi yang tidak kompatibel

Strategi 2: Pengendalian Versi Semantis

Judul Bagian “Strategi 2: Pengendalian Versi Semantis”

Pakai Capgo’s built-in pengendalian versi semantis untuk mencegah pembaruan di batas versi.

Tidak Aktifkan Pembaruan Otomatis di Versi Utama

Judul Bagian “Tidak Aktifkan Pembaruan Otomatis di Versi Utama”
Jendela Terminal
# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

Pengaturan ini berarti:

  • Pengguna di versi aplikasi 1.2.3 akan menerima pembaruan hingga 1.9.9
  • Pengguna akan TIDAK menerima versi 2.0.0 otomatis
  • Mencegah perubahan yang mengganggu mencapai native code
  • Perbandingan menggunakan basis native yang dikirimkan sebagai version_build
Jendela Terminal
# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor
# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch
# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Spesifikkan versi aplikasi natif minimum (“min_update_version) pada setiap paket sehingga Capgo hanya mengirimkannya ke perangkat yang memiliki biner natif yang cukup baru.

Ini menggunakan strategi metadata saluran (“ ) plus metadata saluran--disable-auto-update metadatastrategi ( --min-update-version atau --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Judul bagian: Aktifkan target metadata pada saluran

Jendela terminal
Salin ke clipboard
# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Judul bagian: Tetapkan versi native minimum pada saat unggah

Ketika mengunggah sebuah bundle, masukkan versi native terendah yang mungkin menerima itu:

Jendela terminal

Salin ke clipboard
# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "2.0.0"

Atau biarkan Capgo menetapkan lantai dari kompatibilitas paket native:

Jendela terminal
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version
  1. Plugin Asli Baru Diperlukan

    Jendela Terminal
    # Bundle needs Camera plugin added in v2.0.0
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "2.0.0"
  2. Pembaharuan Asli API yang Mengubah

    Jendela Terminal
    # Bundle uses new Capacitor 6 APIs
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "3.0.0"
  3. Migrasi Perlahan

    Jendela Terminal
    # one-time: enable metadata gating on beta
    npx @capgo/cli@latest channel set beta --disable-auto-update metadata
    # Test bundle only on latest native version
    npx @capgo/cli@latest bundle upload \
    --channel beta \
    --min-update-version "2.5.0"

Strategi 4: Pencegahan Penurunan Otomatis

Judul Bagian “Strategi 4: Pencegahan Penurunan Otomatis”

Mencegah pengguna menerima paket yang lebih tua dari versi native mereka saat ini.

Pada dashboard Capgo:

  1. Pergi ke Saluran context
  2. Pilih saluran Anda Mengaktifkan
  3. “Nonaktifkan penurunan otomatis di native”

Or via CLI:

Atau melalui __CAPGO_KEEP_0__:
npx @capgo/cli@latest channel set production --no-downgrade
  • Perangkat pengguna: Versi asli 1.2.5
  • Salinan kanal: Versi 1.2.3
  • Hasil: Perbaruan diblokir (akan menjadi penurunan versi)

Hal ini berguna ketika:

  • Pengguna secara manual menginstal versi yang lebih baru dari toko aplikasi
  • Anda perlu memastikan pengguna selalu memiliki patch keamanan terbaru
  • Anda ingin mencegah bug regresi

Override pengaturan saluran untuk perangkat atau kelompok pengguna tertentu.

Gunakan Versi Spesifik untuk Pengujian

Judul Bagian: 'Gunakan Versi Spesifik untuk Pengujian'
import { CapacitorUpdater } from '@capgo/capacitor-updater'
// Force beta testers to use v3 channel
async function assignBetaTesters() {
const deviceId = await CapacitorUpdater.getDeviceId()
// Check if user is beta tester
if (isBetaTester(userId)) {
await CapacitorUpdater.setChannel({ channel: 'v3' })
}
}

Pada Capgo dashboard:

  1. Pergi ke Perangkat → Cari perangkat
  2. Klik Pilih Saluran atau Pilih Versi
  3. Override dengan versi saluran atau paket tertentu
  4. Ponsel akan menerima update dari sumber yang diubah

Berikut adalah contoh lengkap yang menggabungkan semua strategi:

Jendela Terminal
# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
--disable-auto-update metadata \
--no-downgrade
capacitor.config.ts
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production',
}
}
};

2. Perubahan Penerbitan (Aplikasi v2.0.0)

Judul Bagian “2. Perubahan Penerbitan (Aplikasi v2.0.0)”
Jendela Terminal
# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
--disable-auto-update metadata \
--no-downgrade \
--self-assign
# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance
// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // New users get v2 channel
}
}
};
Jendela terminal
# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "1.0.0"
# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
--channel v2 \
--min-update-version "2.0.0"

Pakai dashboard Capgo untuk melacak:

  • Banyaknya pengguna pada v1 vs v2
  • Rasio penggunaan paket per versi
  • Kerusakan atau kegagalan per versi

Setelah penggunaan v1 turun di bawah ambang batas:

Jendela terminal
# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance
# Move all remaining users to default
# (They'll need to update via app store)

Ketika ada beberapa konfigurasi saluran, Capgo menggunakan urutan prioritas berikut:

  1. Override Perangkat (Dashboard atau API) - Prioritas tertinggi dan terlihat di UI Override Perangkat
  2. Saluran Plugin Lokal via setChannel() - Tersimpan di perangkat hanya dan tidak ditampilkan di UI Override Perangkat
  3. defaultChannel dalam capacitor.config.ts
  4. Saluran Default (Pengaturan Cloud) - Prioritas Terendah

1. Selalu Tetapkan defaultChannel untuk Versi Utama

Judul Bagian: “1. Selalu Atur defaultChannel untuk Versi Utama”
// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3
// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually
Jendela Terminal
# ✅ Good
1.0.0 1.0.1 1.1.0 2.0.0
# ❌ Bad
1.0 1.1 2 2.5
Jendela Terminal
# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions
Jendela terminal
# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel first
npx @capgo/cli@latest bundle upload \
--channel beta \
--auto-min-update-version
# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version

Periksa dashboard Anda secara teratur:

  • Apakah pengguna mengupgrade ke versi native yang lebih baru?
  • Apakah versi lama masih mendapatkan lalu lintas yang tinggi?
  • Apakah Anda harus menghentikan penggunaan kanal-kanal lama?

Untuk tim yang beralih dari Ionic AppFlowdi sini adalah bagaimana Capgo membandingkan target versi:

FiturAppFlow IonicCapgo
Pengaturan Versi Berdasarkan RutePengaturan Versi Otomatis Berdasarkan Versi AsliPengaturan Versi Otomatis Melalui defaultChannel + Strategi Banyak
Pengaturan Versi SemantikDukungan DasarDukungan Lanjutan dengan --disable-auto-update (versi mayor/minor/patch)
Pengikat Versi AsliKonfigurasi Manual di Dashboard AppFlowBawaan --min-update-version / --auto-min-update-version dengan Saluran Metadata
Pengelolaan SaluranWeb UI + CLIWeb UI + CLI + API
Antarmuka Web + __CAPGO_KEEP_0__ + __CAPGO_KEEP_1__Pengaturan PerangkatFull control via Dashboard/API
Penuh Kontrol melalui Dashboard/__CAPGO_KEEP_0__Pencegahan Penurunan OtomatisYa melalui --no-downgrade
Pemeliharaan multi-versiPengelolaan cabang/tujuan manualDengan otomatisasi dan keutamaan saluran
Penyimpanan sendiriTidakYa (pengendalian penuh)
Analisis versiSederhanaMetrik per-versi yang rinci

context: Judul bagian: Judul bagian ‘Pengguna Tidak Menerima Perbarui’

  1. Pengaturan Judul: Pengguna Tidak Menerima PerbaruiLihat hal-hal berikut:

    const channel = await CapacitorUpdater.getChannel()
    console.log('Current channel:', channel)
  2. : Pastikan perangkat berada di saluran yang benar. Salin ke clipboard. Batasan Versi: Periksa apakah paket memiliki persyaratan versi native

    • Dashboard → Paket → Periksa kolom “Versi Native”
  3. Pengaturan Semver: Pastikan saluran memiliki disable-auto-update Pengaturan

    Jendela Terminal
    npx @capgo/cli channel list
  4. Override Perangkat: Periksa apakah perangkat memiliki override manual

    • Dashboard → Perangkat → Cari perangkat → Periksa saluran/versi
  1. Ulasan saluran default: Pastikan saluran yang benar di capacitor.config.ts
  2. Periksa Unggah Paket: Pastikan paket telah diunggah ke saluran yang dimaksudkan
  3. Periksa versi update minimum: Konfirmasi --min-update-version (atau --auto-min-update-version) telah ditetapkan dan saluran menggunakan --disable-auto-update metadata

Pembaharuan Mendasar yang Mempengaruhi Versi Lama

Judul bagian “Pembaharuan Mendasar yang Mempengaruhi Versi Lama”
  1. Pemecahan Sementara: Atur ulang perangkat yang terpengaruh ke paket aman
    • Dashboard → Perangkat → Pilih banyak → Atur Versi
  2. Pembaruan Jangka Panjang: Buat saluran dengan versi dan jaga cabang terpisah
  3. Pencegahan: Selalu tes pembaruan pada perangkat wakil sebelum peluncuran

Jika Anda sedang memindahkan dari Ionic AppFlow, target versi bekerja sangat mirip di Capgo, dengan fleksibilitas yang ditingkatkan:

Konsep AppFlowCapgo Sama denganCatatan
Jalur DeployCapgo JalurKonsep yang sama, lebih kuat
Pemutakhiran Versi Asli--min-update-version / --auto-min-update-versionKontrol yang lebih halus
Prioritas JalurPrecedensi Jalur (override → awan → default)Precedensi yang lebih transparan
Target PemutakhiranSaluran + semver mengontrolStrategi yang tersedia secara berlimpah
Saluran Produksiproduction saluran (atau nama apa pun)Penamaan yang Fleksibel
Penyalinan berbasis GitCLI unggah bundle dari cabangAlur Kerja yang Sama
Pembaruan Otomatis yang SesuaidefaultChannel + batasan versiDiperkuat dengan strategi yang berlimpah
  1. Kontrol Lebih Banyak: Capgo memberikan Anda strategi-strategi yang berbeda (saluran, semver, versi native) yang dapat digabungkan
  2. Keterlihatan Lebih Baik: Dashboard menampilkan distribusi versi dan masalah kompatibilitas
  3. API Akses: Kontrol penuh programatik atas target versi
  4. Penggunaan Sendiri: Opsi untuk menjalankan server pembaruan sendiri dengan logika versi yang sama
  1. Peta Saluran AppFlow Anda ke Capgo saluran (biasanya 1:1)
  2. Set defaultChannel di capacitor.config.ts untuk setiap versi utama
  3. Konfigurasi aturan semver jika Anda ingin pemblokiran otomatis di batas versi
  4. Muat bundle khusus versi menggunakan --min-update-version (saluran harus menggunakan strategi metadata)
  5. Pantau distribusi versi di Capgo dashboard

Rollout Berangsur-angsurnya oleh Versi

Bab berjudul “Rollout Berangsur-angsurnya oleh Versi”
// Gradually migrate v1 users to v2
async function migrateUsers() {
const deviceId = await CapacitorUpdater.getDeviceId()
const rolloutPercentage = 10 // Start with 10%
// Hash device ID to get deterministic percentage
const hash = hashCode(deviceId) % 100
if (hash < rolloutPercentage) {
// User is in rollout group - migrate to v2
await CapacitorUpdater.setChannel({ channel: 'v2' })
}
}
// Enable features based on native version
async function checkFeatureAvailability() {
const info = await CapacitorUpdater.getDeviceId()
const nativeVersion = info.nativeVersion
if (compareVersions(nativeVersion, '2.0.0') >= 0) {
// Enable features requiring v2.0.0+
enableNewCameraFeature()
}
}
// Run A/B tests within same native version
async function assignABTest() {
const nativeVersion = await getNativeVersion()
if (nativeVersion.startsWith('2.')) {
// Only A/B test on v2 users
const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
await CapacitorUpdater.setChannel({ channel: variant })
}
}

Capgo menyediakan beberapa strategi untuk pengiriman pembaruan versi tertentu:

  1. Routing Berdasarkan Saluran: Pemisahan versi otomatis melalui defaultChannel
  2. Versi Semantik: Mencegah pembaruan di batas besar/kecil/patch
  3. Keterbatasan Versi Nativ: Membutuhkan versi natif minimum untuk bundle
  4. Pencegahan Turun Versi Otomatis: Tidak pernah kirim bundle yang lebih tua ke versi native yang lebih baru
  5. Penyesuaian Perangkat: Kontrol manual untuk pengujian dan targeting

Dengan menggabungkan strategi-strategi ini, Anda dapat mencapai pengiriman update otomatis AppFlow dengan fleksibilitas dan kontrol yang lebih banyak. Pilihlah pendekatan yang paling sesuai dengan alur versi dan pengiriman aplikasi Anda.

Untuk informasi lebih lanjut tentang fitur-fitur tertentu:

Jika Anda menggunakan Targeting Versi untuk merencanakan routing saluran dan peluncuran tahap demi tahap, hubungkannya dengan Saluran untuk detail implementasi di Saluran, Saluran untuk detail implementasi di Saluran, Saluran untuk detail implementasi di Saluran, Solusi Uji Coba Beta untuk alur kerja produk di Solusi Uji Coba Beta, dan Solusi Target Versi untuk alur kerja produk di Solusi Target Versi.