Target Versi

seperti pendekatan Ionic AppFlow. Panduan ini menjelaskan cara mengirimkan bundle yang kompatibel terbaru 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 "Migrasi AppFlow" untuk instruksi migrasi langkah demi langkah. Panduan Migrasi AppFlow Ringkasan

Sistem target versi __CAPGO_KEEP_0__ memungkinkan Anda:

Capgo’s version targeting system allows you to:

• Mencegah perubahan yang mengganggu Sistem target versi __CAPGO_KEEP_0__ memungkinkan Anda mengirimkan update yang kompatibel secara otomatis ke pengguna berdasarkan versi aplikasi native mereka, serta mencegah perubahan yang mengganggu.
• Sistem target versi __CAPGO_KEEP_0__ memungkinkan Anda mengirimkan update yang kompatibel secara otomatis ke pengguna berdasarkan versi aplikasi native mereka, serta mencegah perubahan yang mengganggu. dari mencapai versi aplikasi yang tidak kompatibel
• Kelola versi aplikasi yang berbeda secara bersamaan tanpa logika kompleks
• Dapatkan pembaruan yang lancar ke segmen pengguna tertentu

Mengapa Targeting Versi Penting (Terutama bagi Pengguna AppFlow)

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

Capgo menyediakan jaminan keamanan yang sama, dengan fitur tambahan:

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

Pendekatan 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 mundur sambil mengeluarkan perubahan yang mengganggu
• Anda ingin mencegah bundle yang lebih baru mengganggu native code yang lebih tua
• Anda sedang memigrasikan pengguna secara bertahap dari satu versi ke versi lain
• Anda sedang memigrasikan dari AppFlow dan ingin mempertahankan keamanan update yang sama

Cara Kerjanya

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

1. Keterbatasan Versi Asli: Mencegah bundle untuk dikirimkan ke versi native yang tidak kompatibel
2. Pengaturan Rute Berdasarkan Saluran: Mengarahkan versi aplikasi yang berbeda ke saluran pembaruan yang berbeda
3. Kontrol Semantik Versi: Otomatis memblokir pembaruan di batas major/minor/patch
4. Pengaturan Pengabaian pada 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 defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

Strategi 1: Rute Versi Berdasarkan Saluran

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

Skenario Contoh

• App v1.x (100.000 pengguna) → production saluran
• App v2.x (50.000 pengguna dengan perubahan besar) → 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 Bundel yang Spesifik untuk Versi

# 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 bundel aplikasi yang terinstal. Tidak perlu mengubah kode JavaScript code!

Kelebihan

• Tidak ada perubahan code apa pun - Pengaturan saluran terjadi secara otomatis
• Pengaturan yang jelas - Setiap versi memiliki jalur pembaruan sendiri
• Target yang fleksibel - Push pembaruan ke kelompok versi tertentu
• Rollout yang aman - Perubahan yang memecah tidak pernah mencapai versi yang tidak kompatibel

Strategi 2: Pengendalian Versi Semantik

Gunakan Capgo’s pengaturan versi semantik bawaan untuk mencegah pembaruan di antara batas versi.

Matikan Pembaruan Otomatis di Antara Versi Utama

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

Konfigurasi ini berarti:

• Pengguna pada versi aplikasi 1.2.3 akan menerima pembaruan hingga 1.9.9
• Pengguna akan TIDAK menerima versi 2.0.0 otomatis secara
• Mencegah perubahan yang mengganggu dari versi native code

Opsi Kontrol yang Rinci

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (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 akan berhasil 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 native minimum untuk bundle untuk mencegah pengiriman ke perangkat yang tidak kompatibel.

Menggunakan nativeVersion Delay Condition

Ketika mengunggah sebuah bundle, Anda dapat menentukan versi native minimum:

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

Cara Kerja

Perangkat pada versi native 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 native baru.

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. Menghancurkan Native API Perubahan

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

3. Migrasi Berperingkat

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

Strategi 4: Pencegahan Downgrade Otomatis

Mencegah pengguna menerima paket 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 auto downgrade di native”
3. Simpan perubahan

Atau melalui 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

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 Penggeser Perangkat

Di dashboard Capgo:

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

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

Gunakan dashboard Capgo untuk melacak:

• Berapa banyak pengguna yang menggunakan v1 vs v2
• Rasio penggunaan bundel 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, Capgo menggunakan urutan prioritas ini:

1. Override Perangkat (Dashboard atau API) - Prioritas tertinggi
2. Override Cloud melalui setChannel() panggilan
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 perangkat mereka ke 'beta' di dashboard, mereka akan menerima pembaruan dari 'beta' saluran.

Praktik Terbaik

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

# 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 tinggi?
• Apakah Anda harus menghentikan penggunaan saluran lama?

Perbandingan dengan Ionic AppFlow

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

Fitur	Ionic AppFlow	Capgo
Routing berdasarkan versi	Berbasis otomatis pada versi asli	Otomatis melalui defaultChannel + strategi berbasis native
Versi semantik	Support dasar	Maju dengan --disable-auto-update (maju/minor/patch)
Keterbatasan versi native	Konfigurasi manual di dashboard AppFlow	Tersedia secara bawaan --native-version flag di CLI
Pengelolaan saluran	UI Web + CLI	UI Web + CLI + API
Pengaturan Perangkat	Kontrol Terbatas pada Perangkat	Kontrol Lengkap melalui Dashboard/API
Pencegahan Downgrade Otomatis	Ya	Ya melalui --disable-downgrade
Pemeliharaan Versi Multi	Pengelolaan Cabang/Tingkat Manual	Dengan Otomatisasi Prioritas Saluran
Self-Hosting	Tidak	Ya (pengendalian penuh)
Analitik versi	Dasar	Metrik versi per-versi yang rinci

Keserupaan AppFlow dan Lebih Lanjut

Capgo menyediakan semua kemampuan target versi yang ditawarkan AppFlow, plus mekanisme pengendalian tambahan. Jika Anda bergantung pada AppFlow’s pencocokan otomatis versi, Anda akan menemukan __CAPGO_KEEP_0__ sama aman dengan lebih fleksibel. that AppFlow offered, plus additional control mechanisms. If you relied on AppFlow’s automatic version matching, you’ll find Capgo equally safe with more flexibility.

Bagian berjudul “Pengaturan”

Pengguna Tidak Menerima Perbaruan

Periksa hal-hal berikut:

1. Penugasan Saluran: Pastikan 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 Asli”

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

   npx @capgo/cli channel list

4. Override Perangkat: Periksa apakah perangkat memiliki override manual

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

Bundle Diteruskan ke Versi yang Salah

1. Ulangi defaultChannel: Pastikan saluran yang benar dalam capacitor.config.ts
2. Periksa Unggah Bundle: Pastikan bundle telah diunggah ke saluran yang diinginkan
3. Inspeksi Versi Asli: Konfirmasi --native-version flag digunakan dengan benar

Pembaharuan Berbahaya yang Mempengaruhi Versi Lama

1. Pemulihan Sementara: Mengatur perangkat yang terpengaruh ke bundle aman
   • Dashboard → Perangkat → Pilih banyak → Set Versi
2. Pemulihan Jangka Panjang: Buat saluran yang versi dan jaga cabang yang terpisah
3. Pencegahan: Selalu tes pembaruan pada perangkat perwakilan sebelum peluncuran

Migrasi dari Ionic AppFlow

Jika Anda sedang melakukan migrasi dari Ionic AppFlow, versi targeting bekerja sangat mirip di Capgo, dengan fleksibilitas yang lebih baik:

Peta Konsep

Konsep AppFlow	Capgo Sama Konsep, Lebih Kuat	Catatan
Saluran Deploy	Capgo Saluran	Konsep yang sama, lebih kuat
Versi Lokal Asli	--native-version __CAPGO_KEEP_0__	Kontrol yang lebih halus
Prioritas Saluran	Precedensi Saluran (override → cloud → default)	Precedensi yang lebih transparan
Target Pengembangan	Saluran + semver mengontrol	Banyak strategi tersedia
Saluran Produksi	production saluran (atau nama apa pun)	Penamaan yang fleksibel
Deployan berbasis Git	CLI unggah bundle dari cabang	Alur kerja yang sama
Pembaruan otomatis berdasarkan versi	defaultChannel Konstrain versi yang lebih tinggi	Diperkuat dengan strategi yang lebih dari satu

Perbedaan Utama bagi Pengguna AppFlow

1. Pengendalian yang lebih baik: Capgo memberikan Anda strategi yang lebih dari satu (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. Penghosan Sendiri: Opsi untuk menjalankan server pembaruan sendiri dengan logika versi yang sama

Langkah Migrasi

1. Peta Saluran Aplikasi Anda ke saluran Capgo (biasanya 1:1)
2. Atur defaultChannel di capacitor.config.ts untuk setiap versi utama
3. Konfigurasi Aturan Semver Jika Anda ingin blokir otomatis pada batasan versi
4. Upload bundle spesifik versi dengan 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 Petunjuk Migrasi AppFlow ke Capgo.

Polakan Lanjutan

Rollout Berperingkat 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 yang spesifik oleh versi:

1. Rute Berbasis Saluran: Pemisahan versi otomatis melalui defaultChannel
2. Pengaturan Versi Semantik: Mencegah pembaruan di batas major/minor/patch
3. Keterbatasan Versi Asli: Mengharuskan versi asli minimum untuk bundle
4. Pencegahan Penurunan Otomatis: Tidak pernah mengirimkan 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 pembaruan otomatis AppFlow dengan fleksibilitas dan kontrol yang lebih banyak. Pilih pendekatan yang paling sesuai dengan alur versi dan pengiriman aplikasi Anda.

Untuk informasi lebih lanjut tentang fitur-fitur tertentu:

• Panduan Perubahan yang Berubah - Strategi versi saluran yang rinci
• Pengelolaan Saluran - Referensi konfigurasi saluran yang lengkap
• Sikap Perbarui - Keterlambatan versi native dan kondisi