Pengaturan Versi

Panduan ini menjelaskan cara mengirimkan bundle yang paling kompatibel ke pengguna berdasarkan versi aplikasi asli mereka, seperti pendekatan Ionic AppFlowini memastikan manajemen update yang lebih sederhana dan peluncuran yang lebih cepat sambil mencegah masalah kompatibilitas.

Mengalihkan dari Ionic AppFlow?

If Anda berasal dari Ionic AppFlow, panduan ini sangat penting bagi Anda. AppFlow secara otomatis memasangkan pembaruan ke versi native, dan Capgo menyediakan kemampuan yang sama dengan kontrol dan fleksibilitas yang lebih banyak. Lihat panduan "Migrasi AppFlow" untuk instruksi migrasi langkah demi langkah. Migrasi AppFlow Ringkasan

Bab berjudul "Ringkasan"

Capgo’s version targeting system allows you to:

• ke pengguna berdasarkan versi aplikasi native mereka Mencegah perubahan yang memecah
• agar tidak mencapai versi aplikasi yang tidak kompatibel Mengelola versi aplikasi
• berbagai versi secara bersamaan tanpa logika kompleks Automatis deliver pembaruan yang kompatibel
• Melakukan pembaruan secara lancar ke segmen pengguna tertentu Mengapa Targeting Versi Penting (Terutama bagi Pengguna AppFlow)

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

Ionic AppFlow , Anda tahu betapa pentingnya memastikan pengguna hanya menerima pembaruan yang kompatibel. AppFlow secara otomatis memasangkan paket pembaruan live ke versi aplikasi native, sehingga JavaScript yang tidak kompatibel tidak akan disampaikan ke versi native __CAPGO_KEEP_0__.code menyediakan jaminan keamanan yang sama

Capgo provides the same safety guaranteesPengendalian yang lebih halus atas matching versi

• Strategi yang lebih dari satu (saluran, semver, konstrain native)
• Keterlihatan yang lebih baik atas distribusi versi
• Melakukan pembaruan secara lancar ke segmen pengguna tertentu
• API dan CLI mengontrol bersama dengan manajemen dashboard

Metode ini sangat berguna ketika:

• Pada saat Anda memiliki pengguna di berbagai versi utama aplikasi Anda (misalnya, v1.x, v2.x, v3.x)
• Pada saat Anda perlu mempertahankan konsistensi ke belakang sambil mengeluarkan perubahan yang mengganggu
• Pada saat Anda ingin mencegah bundle yang lebih baru mengganggu native code yang lebih tua
• Pada saat Anda sedang melakukan migrasi pengguna secara bertahap dari satu versi ke versi lain
• Pada saat Anda sedang melakukan migrasi dari AppFlow dan ingin mempertahankan keamanan update yang sama

Bagaimana Cara Kerjanya

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

1. Keterbatasan Versi NativeMencegah bundle dari dikirimkan ke versi native yang tidak kompatibel
2. Rute Berbasis SaluranMencegah pembaruan secara otomatis di batas major/minor/patch
3. Mengatasi Perangkat secara SpesifikAlur Pembaruan Versi
4. Bagian berjudul “Alur Pembaruan Versi”Salin ke clipboard

Strategi 1: Rute Versi Berbasis Saluran

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]

Salin ke clipboard

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

Skenario Contoh

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

Implementasi

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
    }
  }
};

Langkah 2: Buat Saluran

# 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

Langkah 3: Unggah Paket Versi-Spesifik

# 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

Pengaturan Otonom

Ketika pengguna membuka aplikasi, mereka secara otomatis terhubung ke saluran yang ditentukan berdasarkan defaultChannel dalam paket aplikasi yang terinstal. Tidak perlu mengubah JavaScript code apa pun!

Manfaat

• Perubahan code apa pun - Routing kanal terjadi secara otomatis
• Penyebaran yang jelas - Setiap versi memiliki jalur pembaruan sendiri
• Target yang fleksibel - Kirim pembaruan ke kelompok versi tertentu
• Pembaruan yang aman - Perubahan yang mengganggu tidak akan mencapai versi yang tidak kompatibel

Strategi 2: Pengendalian Versi Semantik

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

Matikan Perbarui Otomatis di Versi Utama

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

Konfigurasi ini berarti:

• Pengguna di versi aplikasi 1.2.3 akan menerima perbarui hingga 1.9.9
• Pengguna akan TIDAK menerima versi 2.0.0 otomatis
• Mencegah perubahan yang mengganggu mencapai native code
• Penggunaan perbandingan menggunakan basis sentesis native yang dikirim sebagai version_build

Opsi Kontrol Granular

# 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

Diperlukan Semantik Versi

Strategi ini hanya berfungsi jika Anda mengikuti semantik versi (semver) untuk versi aplikasi Anda. Pastikan nomor versi Anda mengikuti MAJOR.MINOR.PATCH format.

Strategi 3: Konstrain Versi Native

Tentukan persyaratan versi asli minimum untuk bundle untuk mencegah pengiriman ke perangkat yang tidak kompatibel.

Menggunakan kondisi penundaan nativeVersion

Ketika mengunggah bundle, Anda dapat menentukan versi asli minimum:

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

Cara Kerjanya

Perangkat pada versi 1.x tidak akan menerima bundle ini. Hanya perangkat pada 2.0.0+ yang akan mendapatkannya. Ini sangat cocok untuk pembaruan yang memerlukan API atau plugin asli baru.

Contoh Penggunaan

1. Plugin Native Baru Diperlukan

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. Perubahan Native API yang Mengganggu

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. Migrasi Gradual

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

Mencegah Auto-Downgrade dengan Strategi 4

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

Aktifkan di Pengaturan Saluran

Di dashboard Capgo:

1. Buka Saluran → Pilih saluran Anda
2. Aktifkan “Disable auto downgrade under native”
3. “Nonaktifkan auto downgrade di native”

Or via CLI:

npx @capgo/cli channel set production --disable-downgrade

Contoh

• Perangkat pengguna: Versi asli 1.2.5
• Bundel saluran: 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

Strategi 5: Targeting Tingkat Perangkat

Atur saluran pengganti untuk perangkat atau kelompok pengguna tertentu.

Forcing Specific Version for Testing

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' })
  }
}

Dashboard Pengganti Perangkat

Di dashboard Capgo :

1. Lihat Perangkat → Cari perangkat
2. Klik Tetapkan Saluran atau Atur Versi
3. __CAPGO_KEEP_0__ dengan versi kanal atau paket tertentu
4. Perangkat akan menerima pembaruan dari sumber yang di-overriden

Menguji Pembaruan

Gunakan pengaturan perangkat untuk menguji pembaruan pada perangkat Anda sendiri sebelum mengeluarkannya untuk semua pengguna

Alur Kerja Lengkap AppFlow-Style

Contoh lengkap yang menggabungkan semua strategi:

1. Pengaturan Awal (Aplikasi v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. Perubahan Pecah (Aplikasi v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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
    }
  }
};

3. Kirim Perbarui ke Versi yang Sama

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. Perbarui Distribusi Versi

Pakai dashboard Capgo untuk mengikuti:

• Banyak pengguna yang menggunakan v1 vs v2
• Rasio penggunaan bundel per versi
• Error atau crash per versi

5. Nonaktifkan Versi Lama

Setelah penggunaan v1 turun di bawah ambang batas:

# 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)

Prioritas Saluran

Ketika ada beberapa konfigurasi saluran yang ada, Capgo menggunakan urutan prioritas ini:

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

Contoh Precedence

Jika aplikasi pengguna memiliki defaultChannel: 'v2' tetapi Anda mengganti perangkat mereka ke 'beta' di dashboard, mereka akan menerima pembaruan dari 'beta' saluran.

Tampilan Penggantian Perangkat hanya menampilkan penggantian yang ditetapkan dari dashboard atau Publik API. Panggilan setChannel() dari aplikasi memvalidasi saluran dengan backend, kemudian menyimpannya secara lokal di perangkat.

Praktik Terbaik

1. Selalu Tetapkan 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

2. Gunakan Versi Semantik

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Jaga Cabang Terpisah

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. Uji Sebelum Peluncuran

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. Distribusi Versi

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 lama?

Perbandingan dengan Ionic AppFlow

Untuk tim yang bermigrasi dari Ionic AppFlowCapgo’s target versi dibandingkan dengan:

Fitur	Aplikasi Ionic Flow	Capgo
Pengaturan Routing Berdasarkan Versi	Otomatis berdasarkan versi native	Otomatis melalui defaultChannel + strategi multiple
Pengaturan Versi Semantik	Pengaturan Dasar	Dengan kemampuan maju --disable-auto-update (versi mayor/minor/patch)
Pengaturan Konstrain Versi Native	Konfigurasi manual di dashboard AppFlow	Tersedia secara bawaan --native-version flag di CLI
Pengelolaan saluran	Web UI + CLI	Web UI + CLI + API
Pengaturan perangkat	Kontrol perangkat terbatas	Kontrol penuh melalui Dashboard/API
Pencegahan downgrade otomatis	Ya	Ya melalui --disable-downgrade
Pemeliharaan multi-versi	Pengelolaan cabang/tujuan manual	Ditangani secara otomatis dengan prioritas tujuan
Penghosan sendiri	Tidak	Ya (pengendalian penuh)
Analitik versi	Dasar	Metrik per-versi rinci

Keserasian AppFlow dan Lebih Lanjut

Capgo menyediakan semua kemampuan target versi yang ditawarkan oleh AppFlow, ditambahkan dengan mekanisme kontrol tambahan. Jika Anda bergantung pada pencocokan versi otomatis AppFlow, Anda akan menemukan Capgo sama aman dengan lebih fleksibel.

Pengaturan

Pengguna Tidak Menerima Perbaruan

Periksa hal berikut:

1. Penugasan Saluran: Pastikan perangkat berada pada saluran yang benar

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. Keterbatasan Versi: Periksa jika paket memiliki persyaratan versi native

   • DASHBOARD → Paket → Periksa kolom "Versi Nama Lokal"

3. Pengaturan Semver: Pastikan saluran disable-auto-update pengaturan

   npx @capgo/cli channel list

4. Tetapkan Ulang Perangkat: Periksa apakah perangkat memiliki pengaturan manual

   • DASHBOARD → Perangkat → Cari perangkat → Periksa saluran/versi

Paket Diteruskan ke Versi Salah

1. Ulas defaultChannel: Pastikan saluran yang benar capacitor.config.ts
2. Check Bundle Upload: Pastikan bundel telah diunggah ke saluran yang diinginkan
3. Inspect Versi Asli: Konfirmasi --native-version flag digunakan dengan benar

Pembaharuan Mendasar yang Mempengaruhi Versi Lama

1. Pemecahan Jangka Pendek: Atur ulang perangkat yang terpengaruh ke bundel yang aman
   • Dashboard → Perangkat → Pilih banyak → Atur Versi
2. Pemecahan Jangka PanjangMembuat saluran yang terverifikasi dan menjaga cabang yang terpisah
3. Pencegahan: Selalu tes pembaruan pada perangkat perwakilan sebelum peluncuran

Migrasi dari Ionic AppFlow

Jika Anda bermigrasi dari AppFlow Ionic, target versi bekerja sangat mirip di Capgo, dengan fleksibilitas yang diperbaiki:

Peta Konsep

Konsep AppFlow	Capgo Sama dengan	Catatan
Tayangkan Saluran	Capgo Saluran	Konsep yang sama, lebih kuat
Versi Asli Pembatasan	--native-version flag	Kontrol yang lebih terperinci
Prioritas Saluran	Sebelumnya Saluran (override → cloud → default)	Prioritas yang lebih transparan
Tujuan Pengiriman	Saluran + kontrol semver	Strategi yang tersedia lebih dari satu
Saluran Produksi	production saluran (atau nama apa pun)	Penamaan yang fleksibel
Pengunggahan berbasis Git	CLI unggah bundle dari cabang	Alur kerja yang sama
Sesuai versi otomatis	defaultChannel Konstrain versi +	Diperkuat dengan strategi yang lebih dari satu

Perbedaan Utama untuk Pengguna AppFlow

1. Kontrol Lebih Baik: Capgo memberikan Anda beberapa strategi (saluran, semver, versi native) yang dapat digabungkan
2. Kontrol Lebih Baik: Dashboard menampilkan distribusi versi dan masalah kompatibilitas
3. API Akses: Kontrol penuh programatis atas target versi
4. Penggunaan Sendiri: Opsi untuk menjalankan server pembaruan sendiri dengan logika versi yang sama

Langkah-Langkah Pemindahan

1. Peta Saluran Aplikasi Anda ke Capgo saluran (biasanya 1:1)
2. Set defaultChannel dalam capacitor.config.ts untuk setiap versi utama
3. Konfigurasi aturan semver jika Anda ingin pemblokiran otomatis di batas versi
4. Upload bundle yang spesifik untuk versi menggunakan --native-version flag
5. Monitor distribusi versi di dashboard Capgo

Petunjuk Penuh Migrasi

Untuk instruksi migrasi lengkap termasuk penggantian SDK dan API mapping, lihat Migrasi Guide AppFlow ke Capgo.

Polakan Lanjutan

Pengeluaran Berkelanjutan 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' })
  }
}

Flag Fitur oleh Versi

// 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()
  }
}

Pengujian A/B di Antara Versi

// 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 })
  }
}

Ringkasan

Capgo menyediakan beberapa strategi untuk pengiriman update spesifik versi:

1. Rute Berbasis Saluran: Pemisahan versi otomatis via defaultChannel
2. Pengaturan Versi Semantik: Mencegah update di antara batasan mayor/minor/patch
3. Keterbatasan Versi Nativ: Mengharuskan versi minimum native untuk bundle
4. Pencegahan Turun Versi Otomatis: Tidak pernah mengirim bundle yang lebih tua ke versi native yang lebih baru
5. Pengaturan PerangkatManual untuk pengujian dan target

Dengan menggabungkan strategi-strategi ini, Anda dapat mencapai pengiriman pembaruan 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:

• Petunjuk Perubahan - Strategi versi saluran yang rinci
• Manajemen Saluran - Referensi konfigurasi saluran yang lengkap
• Pengaturan Pembaruan - Penundaan dan kondisi versi native

Lanjutkan dari Targeting Versi

Jika Anda menggunakan Targeting Versi untuk merencanakan routing saluran dan peluncuran rolut, hubungkannya dengan Saluran untuk detail implementasi di Saluran, Saluran untuk detail implementasi di Saluran, Saluran untuk detail implementasi di Saluran, Solusi Pengujian Beta untuk alur kerja produk di Solusi Pengujian Beta, dan Solusi Targeting Versi untuk alur produk dalam Solusi Targeting Versi.