Targeting Versi

Panduan ini menjelaskan cara mengirimkan bundle yang paling kompatibel ke pengguna berdasarkan versi aplikasi asli mereka. seperti pendekatan Ionic AppFlow. Ini memastikan manajemen update yang lebih sederhana dan peluncuran yang lebih cepat 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 ke versi native, dan Capgo menyediakan kemampuan yang sama dengan kontrol dan fleksibilitas yang lebih banyak. Lihat panduan Panduan Migrasi AppFlow untuk instruksi migrasi langkah demi langkah.

Ringkasan

Sistem target versi Capgo memungkinkan Anda:

• Mengirimkan update yang kompatibel secara otomatis ke pengguna berdasarkan versi aplikasi native mereka
• Mencegah perubahan yang memecah dari mencapai versi aplikasi yang tidak kompatibel
• Kelola versi aplikasi yang berbeda secara bersamaan tanpa logika kompleks
• Dapatkan pembaruan yang halus ke segmen pengguna tertentu

Mengapa Targeting Versi Penting (Terutama untuk Pengguna AppFlow)

Jika Anda familiar dengan Ionic AppFlow, Anda tahu betapa pentingnya untuk memastikan pengguna hanya menerima pembaruan yang kompatibel. AppFlow secara otomatis memasangkan paket pembaruan hidup ke versi aplikasi native, mencegah JavaScript yang tidak kompatibel dari disampaikan ke aplikasi native yang lebih tua code.

Capgo menyediakan jaminan keamanan yang samabersama fitur tambahan:

• Pengendalian 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 pengendalian bersama dengan manajemen 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 mempertahankan konsistensi ke belakang sambil mengeluarkan perubahan yang memecah
• Anda ingin mencegah bundle yang lebih baru memecahkan 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 mempertahankan keamanan update yang sama

How It Works

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

1. Keterbatasan Versi Asli: 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 Kontrol Versi Semantik: Otomatis mengblokir pembaruan di batas major/minor/patch
4. Penyesuaian Tingkat Perangkat: Mengarahkan perangkat atau kelompok pengguna tertentu

Alur Pembaruan yang Sesuai

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

Ini adalah pendekatan yang dianjurkan

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

• Bagian berjudul “Skenario Contoh” Aplikasi v1.x production (100.000 pengguna) →
• Aplikasi v2.x (50.000 pengguna dengan perubahan besar) → v2 saluran
• Aplikasi v3.x (10.000 pengguna beta) → v3 saluran

Penerapan

Bab 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

Rute Otomatis

Ketika pengguna membuka aplikasi, mereka secara otomatis terhubung ke saluran yang ditentukan berdasarkan defaultChannel di dalam bundle aplikasi yang terpasang. Tidak ada perubahan JavaScript code yang diperlukan!

Kelebihan

• Nol code perubahan - Routing kanal terjadi secara otomatis
• Pemisahan yang jelas - Setiap versi memiliki jalur update sendiri
• Target yang fleksibel - Push update ke kelompok versi tertentu
• Rollout yang aman - Perubahan yang memecah tidak mencapai versi yang tidak kompatibel

Strategi 2: Pengendalian Versi Semantik

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

Matikan Pembaruan 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 pembaruan hingga 1.9.9
• Pengguna akan TIDAK menerima versi 2.0.0 otomatis
• Mencegah perubahan yang mengganggu dari 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 Versi Semantik

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

Strategi 3: Konstrain Versi Asli

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

Menggunakan kondisi delay nativeVersion

Saat mengunggah bundle, Anda dapat spesifikkan 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"

Bagaimana Cara Kerjanya

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

Penggunaan

1. Diperlukan Plugin Native Baru

   # 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 Berangsur-angsurnya

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

Strategi 4: Pencegahan Downgrade Otomatis

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

Aktifkan di Pengaturan Saluran

Di dashboard Capgo :

1. Pergi ke Saluran → Pilih saluran Anda
2. Aktifkan “Nonaktifkan downgrade otomatis di native”
3. Simpan perubahan

Atau melalui CLI:

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

Contoh

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

Hal ini berguna ketika:

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

Strategi 5: Targeting Level Perangkat

Tetapkan pengaturan saluran untuk perangkat atau kelompok pengguna tertentu.

Tetapkan 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 Pengaturan Perangkat

Di dashboard Capgo :

1. Pergi ke Perangkat → Cari perangkat
2. Klik Tetapkan Saluran atau Tetapkan Versi
3. Tetapkan saluran atau versi paket tertentu
4. Perangkat akan menerima pembaruan dari sumber yang diubah

Menguji Pembaruan

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

Selesai AppFlow-Style Workflow

Contoh lengkap yang menggabungkan semua strategi ini:

1. Pengaturan Awal (App 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. Rilis Perubahan Break (App 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. Pushkan Perbaruan ke Versi Kedua

# 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. Pantau Distribusi Versi

Gunakan dashboard Capgo untuk melacak:

• Banyaknya pengguna pada v1 vs v2
• Rasio penggunaan bundle per versi
• Kerusakan atau crash 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 Saluran

Jika ada beberapa konfigurasi saluran yang ada, 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() - Disimpan di perangkat hanya dan tidak ditampilkan di UI Override Perangkat
3. Saluran Default di capacitor.config.ts
4. Saluran Default (Pengaturan Cloud) - Prioritas Terendah

Contoh Precedence

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

Hanya UI Penggantian Perangkat yang menampilkan penggantian yang telah ditetapkan dari dashboard atau Publik API. 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. Tes Sebelum Rilis

# 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. Pantau 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 saluran lama?

Perbandingan dengan Ionic AppFlow

Untuk tim yang bermigrasi dari Ionic AppFlow, berikut ini adalah cara Capgo’s versi target membandingkan:

Fitur	Ionic AppFlow	Capgo
Pengaturan routing berdasarkan versi	Otomi berdasarkan versi native	Otomi melalui defaultChannel + beberapa strategi
Pengaturan versi semantik	Dukungan dasar	Maju dengan --disable-auto-update (major/minor/patch)
Keterbatasan versi native	Konfigurasi manual di dashboard AppFlow	Dibangun secara internal --native-version flag di CLI
Pengelolaan saluran	UI Web + CLI	UI Web + CLI + API
Pengaturan perangkat	Kontrol perangkat yang terbatas	Kontrol penuh melalui Dashboard/API
Pencegahan downgrade otomatis	Ya	Ya melalui --disable-downgrade
Pemeliharaan multi-versi	Pengelolaan cabang/tujuan manual	Otomatis dengan keutamaan saluran
Penghosan sendiri	Tidak	Ya (kontrol penuh)
Analitik versi	Dasar	Metrik-metrik per-versi yang rinci

Sama dengan AppFlow, bahkan lebih baik

Capgo menyediakan semua kemampuan target versi yang ditawarkan AppFlow, ditambah dengan mekanisme kontrol tambahan. Jika Anda bergantung pada AppFlow untuk menemukan versi otomatis, Anda akan menemukan Capgo sama amannya dengan lebih fleksibel.

Pengaturan

Pengguna Tidak Menerima Perbaruan

Periksa hal-hal berikut:

1. Penugasan Saluran: Periksa apakah perangkat 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 Native”

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

   npx @capgo/cli channel list

4. Override Perangkat: Periksa apakah perangkat memiliki override manual

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

Bundle Diterima ke Versi yang Salah

1. Review defaultChannelPastikan saluran yang benar di capacitor.config.ts
2. Periksa Unggah Bundle: Verifikasi apakah bundle telah diunggah ke saluran yang dimaksud
3. Periksa Versi Asli: Konfirmasi --native-version flag yang digunakan dengan benar

Perubahan yang Mengganggu Versi Lama

1. Pembaruan Langsung: Mengatur ulang perangkat yang terkena dampak ke bundle aman
   • Dashboard → Perangkat → Pilih perangkat secara massal → Atur Versi
2. Pembaruan Jangka Panjang: Membuat saluran versi dan menjaga cabang yang terpisah
3. Pencegahan: Selalu tes pembaruan pada perangkat perwakilan sebelum peluncuran

Migrasi dari Ionic AppFlow

Ionic AppFlow , target versi bekerja sangat mirip di __CAPGO_KEEP_0__, dengan fleksibilitas yang ditingkatkan: , version targeting works very similarly in Capgo, with improved flexibility:

Peta Konsep

Alur Aplikasi Konsep	Sama dengan Capgo	Catatan
Saluran Deploy	Saluran Capgo	Konsep yang sama, lebih kuat
Mengunci Versi Asli	--native-version Bendera	Kontrol yang lebih rinci
Prioritas Saluran	Prioritas saluran (override → cloud → default)	Prioritas lebih transparan
Target Pengiriman	Saluran + semver mengontrol	Banyak strategi tersedia
Saluran Produksi	production saluran (atau nama apa saja)	Penamaan fleksibel
Pengiriman berbasis Git	CLI unggah bundle dari cabang	Alur kerja yang sama
Pencocokan versi otomatis	defaultChannel + batasan versi	Diperkuat dengan strategi yang berbeda-beda

Perbedaan Utama untuk Pengguna AppFlow

1. Kontrol yang Lebih Baik: Capgo memberikan Anda strategi yang berbeda-beda (saluran, semver, versi native) yang dapat digabungkan
2. Keterlihatan yang Lebih Baik: Dashboard menampilkan distribusi versi dan masalah kompatibilitas
3. API Akses: Kontrol penuh programatis atas target versi
4. Self-Hosting: Option untuk menjalankan server pembaruan sendiri dengan logika versi yang sama

Langkah Migrasi

1. Peta saluran AppFlow 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 blokir otomatis di batas versi
4. Unggah bundle khusus versi menggunakan --native-version flag
5. Peta Distribusi Versi dalam Capgo dashboard

Petunjuk Penuh Migrasi

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

Polanya Lanjutan

Pengeluaran Perlahan 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 pembaruan versi spesifik:

1. Rute Berdasarkan Saluran: Pemisahan versi otomatis via defaultChannel
2. : Mencegah pembaruan di batas major/minor/patchChannel-Based Routing: Automatic version separation via Channel-Based Routing, Semantic Versioning: Prevent updates across major/minor/patch boundaries
3. Konfigurasi Versi Asli: Memerlukan versi native minimum untuk bundle
4. Pencegahan Penurunan Otomatis: Tidak pernah mengirim bundle yang lebih tua ke versi native yang lebih baru
5. Pengaturan Perangkat: Kontrol manual untuk pengujian dan targeting

Dengan menggabungkan strategi-strategi ini, Anda dapat mencapai pengiriman update otomatis AppFlow-style 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 Kritis - Strategi versi saluran rinci
• Pengelolaan Saluran - Referensi konfigurasi saluran lengkap
• Perbarui Sifat - Versi asli menunda dan kondisi

Teruskan dari Targeting Versi

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 Channels, Solusi Pengujian Beta untuk alur kerja produk di Solusi Pengujian Beta, dan Solusi Target Versi untuk alur kerja produk di Solusi Target Versi.