Pengaturan Versi

Panduan ini menjelaskan cara mengirimkan bundle terbaru yang kompatibel ke pengguna berdasarkan versi aplikasi asli mereka, seperti pendekatan Ionic AppFlowMengoptimalkan pengelolaan update dan mempercepat peluncuran sambil mencegah masalah kompatibilitas.

Migrasi dari Ionic AppFlow?

Jika Anda berasal dari Ionic AppFlow, panduan ini sangat penting bagi Anda. AppFlow secara otomatis memasangkan update dengan versi native, dan Capgo menyediakan kemampuan yang sama dengan kontrol dan fleksibilitas yang lebih banyak. Lihat Panduan Migrasi AppFlow Panduan Migrasi AppFlow Untuk instruksi migrasi langkah demi langkah.

Ringkasan

Sistem target versi Capgo memungkinkan Anda untuk:

• ke pengguna berdasarkan versi aplikasi native mereka Ditargetkan ke pengguna berdasarkan versi aplikasi aslinya
• Mencegah perubahan yang memecah mencegah versi aplikasi yang tidak kompatibel
• Manajemen versi aplikasi yang berbeda secara bersamaan tanpa logika kompleks
• Perbaruan yang lancar ke segmen pengguna tertentu

Mengapa Targeting Versi Penting (Terutama bagi Pengguna AppFlow)

Jika Anda sudah familiar dengan Ionic AppFlow, Anda tahu betapa pentingnya memastikan pengguna hanya menerima perbaruan yang kompatibel. AppFlow secara otomatis memasangkan live update bundle dengan versi aplikasi native, sehingga mencegah JavaScript yang tidak kompatibel untuk versi aplikasi native yang lebih tua code.

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:

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

Bagaimana Cara Kerjanya

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

1. Keterbatasan Versi Nativ: Mencegah bundle dari pengiriman ke versi native yang tidak kompatibel
2. Routing 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 Level Perangkat: Mengarahkan perangkat atau kelompok pengguna tertentu

Alur Pencocokan Versi

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 Channel

Ini adalah metode 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 channel
• Aplikasi v2.x (50.000 pengguna dengan perubahan besar) → v2 saluran
• Aplikasi v3.x (10.000 pengguna beta) → v3 saluran

Pengimplementasian

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 add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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 di dalam paket aplikasi yang terpasang. Tidak perlu mengubah kode JavaScript code!

Keuntungan

• Tidak ada perubahan code apa pun - Routing saluran kanal terjadi secara otomatis
• Pemisahan yang jelas - Setiap versi memiliki jalur pembaruan sendiri
• Target yang fleksibel - Sampaikan pembaruan ke kelompok versi tertentu
• Rollout yang aman - Perubahan besar tidak akan mencapai versi yang tidak kompatibel

Strategi 2: Pengendalian Versi Semantik

Gunakan Capgo’s built-in Pengendalian versi semantik bawaan Untuk mencegah pembaruan di batas versi.

Pengaturan Auto-Update yang Dibatasi Versi Utama

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

Konfigurasi ini berarti:

• Pengguna aplikasi versi 1.2.3 Akan menerima pembaruan hingga 1.9.9
• Pengguna akan TIDAK menerima versi 2.0.0 automatically
• Mencegah perubahan yang mengganggu mencapai native code yang lebih tua
• Perbandingan menggunakan basis native yang dikirim sebagai version_build

Opsi Kontrol yang 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 format. MAJOR.MINOR.PATCH format.

Strategi 3: Konstrain Versi Nama Asli

Spesifikasikan versi nama asli aplikasi minimal (min_update_version) pada setiap bundle, sehingga Capgo hanya mengirimkannya ke perangkat yang memiliki biner asli yang cukup baru.

Ini menggunakan strategi metadata saluran ( ) plus atau--disable-auto-update metadata) plus --min-update-version or --auto-min-update-version Terdapat pada unggah. Tidak ada --native-version flag CLI.

aktifkan target metadata pada saluran

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

Tetapkan versi native minimum pada unggah

Saat mengunggah sebuah paket, masukkan versi native terendah yang mungkin menerima:

# 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 menentukan lantai dari kompatibilitas paket native:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

Bagaimana Cara Kerjanya

Dengan strategi metadata, perangkat yang memiliki dasar native (version_build) di bawah paket (' min_update_version skip the update. Only devices on that version or higher receive it. See Kompatibilitas untuk --auto-min-update-version Detail.

Penggunaan Kasus

1. Penggunaan Plugin Native Baru Diperlukan

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Pembaruan Natively API yang Mengubah

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

3. Migrasi Langsung

   # 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 Pengurangan Otomatis

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

Dengan mengaktifkan di Pengaturan Saluran

Pada Capgo dashboard:

1. Pergi ke Saluran Pilih saluran Anda
2. Enable Matikan penurunan otomatis di bawah native
3. “Nonaktifkan auto downgrade di native”

Melalui CLI punya.

npx @capgo/cli@latest channel set production --no-downgrade

Example

• Perangkat pengguna: Versi asli 1.2.5
• Saluran Paket: Versi 1.2.3
• Hasil: Perbaruan diblokir (akan menjadi penurunan versi)

Manfaatnya adalah:

• 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 Level Perangkat

Mengatasi penugasan saluran untuk perangkat atau kelompok pengguna tertentu.

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

Dashboard Penggantian Perangkat

Pada Capgo dashboard:

1. Pergi ke Perangkat Temukan perangkat
2. Click Klik or Set Versi
3. Override dengan spesifik saluran atau versi paket
4. Ponsel akan menerima pembaruan dari sumber yang diubah

Tes Pembaruan

Gunakan pengaturan perangkat untuk menguji pembaruan di 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, 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

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

3. Kirim Perbarui ke Versi Kedua

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

4. Pantau Distribusi Versi

Pakai dashboard Capgo untuk melacak:

• Banyak pengguna yang menggunakan v1 vs v2
• Rasio penggunaan paket per versi
• Kerusakan atau kegagalan per versi

5. Deprecate 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 Channel

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

1. Mengatasi Perangkat (Dashboard atau API) - Prioritas tertinggi dan terlihat di UI Penggeser Perangkat
2. Saluran Plugin Lokal via setChannel() - Tersimpan di perangkat hanya dan tidak ditampilkan di UI Mengatasi Perangkat
3. saluranDefault dalam 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.

Antarmuka Penggantian Perangkat hanya menampilkan penggantian yang ditetapkan dari dashboard atau Publik API. Panggilan setChannel() Dari aplikasi memvalidasi saluran dengan backend, lalu 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 Diluncurkan

# 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

5. Periksa 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?
• Should you deprecate old channels?

Perbandingan dengan Ionic AppFlow

Untuk tim yang beralih dari Ionic AppFlowberikut ini adalah bagaimana Capgo membandingkan target versi:

Fitur	App Ionic Flow	Capgo
Pengaturan Versi Berdasarkan Rute	Pengaturan Otomatis Berdasarkan Versi Nadi	Pengaturan Otomatis Melalui defaultChannel + Strategi Banyak
Pengaturan Versi Semantik	Dukungan Dasar	Dukungan Lanjutan dengan --disable-auto-update (Major/Minor/Patch)
Pengaturan Versi Nadi	Pengaturan Tangan di Dashboard AppFlow	Built-in --min-update-version / --auto-min-update-version dengan saluran metadata
Pengelolaan Saluran	Antarmuka Web + CLI	Antarmuka Web + CLI + API
Pengaturan Perangkat	Kontrol terbatas pada tingkat perangkat	Penuh melalui Dashboard/API
Pencegahan penurunan otomatis	Ya	Ya melalui --no-downgrade
Pemeliharaan multi-versi	Pengelolaan cabang/manual secara manual	Dengan otomatisasi dan keutamaan saluran
Self-hosting	Tidak	Ya (pengendalian penuh)
Analisis versi	Sederhana	Metrik per-versi yang rinci

Kesetaraan AppFlow dan Lebih Lanjut

Capgo menyediakan semua kemampuan target versi yang ditawarkan oleh AppFlow, plus kontrol tambahan mekanisme. Jika Anda bergantung pada AppFlow’s versi otomatis matching, Anda akan menemukan Capgo sama aman dengan lebih fleksibilitas.

Troubleshooting

Pengguna Tidak Menerima Perbaruan

Periksa hal-hal berikut:

1. Pengaturan Saluran: Pastikan perangkat Anda berada di saluran yang benar

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

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

   • Dashboard → Paket → Periksa kolom ‘Versi Asli’

3. Pengaturan Semver: Verifikasi saluran’s disable-auto-update Pengaturan

   npx @capgo/cli channel list

4. Tidak Langsung: Periksa jika perangkat memiliki pengaturan manual

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

Bundle Dikirimkan ke Versi Salah

1. Ulas defaultChannel: Pastikan saluran yang benar di capacitor.config.ts
2. Periksa Unggahan Paket: Pastikan paket telah diunggah ke saluran yang diinginkan
3. Periksa versi update terbaru: Konfirmasi --min-update-version (atau --auto-min-update-versionChannel tersebut menggunakan versi yang ditargetkan. --disable-auto-update metadata

Perubahan Mendasar yang Mempengaruhi Versi Lama

1. Perbaikan Langsung: Mengatur ulang perangkat yang terpengaruh ke bundle aman
   • : Atur perangkat yang terpengaruh ke paket aman
2. Patch Jangka Panjang: Buat saluran versi dan jaga cabang terpisah
3. Preventif: Selalu tes pembaruan pada perangkat perwakilan sebelum peluncuran

Migrasi dari Ionic AppFlow

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

Peta Konsep

Konsep AppFlow	Capgo Sama Dengan	Catatan
Saluran Deploy	Capgo Saluran	Konsep yang sama, lebih kuat
Pembaruan Versi Asli	--min-update-version / --auto-min-update-version	Kontrol yang lebih halus
Prioritas Saluran	Precedensi Saluran (override → cloud → default)	Precedensi yang lebih transparan
Target Pembaruan	Saluran + semver mengontrol	Strategi yang tersedia lebih dari satu
Saluran Produksi	production saluran (atau nama lain)	Penamaan Fleksibel
Penyalinan Berbasis Git	CLI unggah bundle dari cabang	Alur Kerja yang Sama
Pemilihan Versi Otomatis	defaultChannel Konstrain Versi (+)	Diperkuat dengan Strategi Banyak

Perbedaan Utama bagi Pengguna AppFlow

1. Pengendalian Lebih Lengkap: Capgo memberikan strategi yang berbeda-beda (saluran, semver, versi native) yang dapat digabungkan
2. Keterlihatan yang Lebih Baik: Dashboard menampilkan distribusi versi dan masalah kompatibilitas
3. : Akses API: Kontrol Penuh Programatik atas Target Versi
4. Self-Hosting: Opsi untuk menjalankan server pembaruan sendiri dengan logika versi yang sama

Langkah-Langkah Pemindahan

1. Peta Saluran AppFlow Anda ke Capgo saluran (biasanya 1:1)
2. Setelkan ‘ defaultChannel di capacitor.config.ts untuk setiap versi utama
3. Konfigurasi aturan semver jika Anda ingin pemblokiran otomatis di batas versi
4. Unggah paket versi tertentu menggunakan --min-update-version (saluran harus menggunakan strategi metadata)
5. Monitor distribusi versi di Capgo dashboard

Petunjuk Penuh Migrasi

Untuk instruksi migrasi lengkap termasuk SDK pengganti dan API pemetaan, lihat Petunjuk Migrasi dari AppFlow ke Capgo.

Pola Lanjutan

Rollout Berangsur-angsur 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' })
  }
}

Bendera 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 yang spesifik versi:

1. Routing Berdasarkan Saluran: Pemisahan versi otomatis melalui defaultChannel
2. Versi Semantik: Mencegah update di antara batas-batas mayor/minor/patch
3. Keterbatasan Versi Asli: Mengharuskan versi asli minimum untuk bundle
4. Pencegahan Turun Versi OtomatisTidak pernah kirim bundle yang lebih lama ke versi native yang lebih baru
5. Pengaturan Perangkat: Kontrol manual untuk pengujian dan targeting

Oleh karena itu, Anda dapat mencapai pengiriman pembaruan otomatis AppFlow dengan lebih fleksibel dan kontrol dengan menggabungkan strategi-strategi ini. Pilihlah pendekatan yang paling sesuai dengan alur versi dan pengiriman aplikasi Anda.

Untuk informasi lebih lanjut tentang fitur tertentu:

• Petunjuk Perubahan Break - Strategi versi kanal rinci
• Pengelolaan Kanal - Referensi konfigurasi kanal lengkap
• Behavior Pembaruan - Penundaan dan kondisi versi asli

Teruskan dari Targeting Versi

Jika Anda menggunakan Pengaturan 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, Pengujian Beta Solusi untuk alur kerja produk di Pengujian Beta Solusi, dan Pengaturan Versi Solusi untuk alur kerja produk di Pengaturan Versi Solusi.