Target Versi

Petunjuk ini menjelaskan cara mengirimkan bundle yang paling kompatibel secara otomatis kepada pengguna berdasarkan versi aplikasi aslinya. mirip dengan pendekatan Ionic AppFlowMengatur update yang lebih sederhana dan peluncuran yang lebih cepat sambil mencegah masalah kompatibilitas.

Mengalihkan dari Ionic AppFlow?

Jika Anda berasal dari Ionic AppFlow, maka 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. Lihatlah Petunjuk Migrasi Aplikasi Untuk instruksi migrasi langkah demi langkah.

Ringkasan

Capgo’s sistem target versi memungkinkan Anda:

• Mengirimkan pembaruan yang kompatibel secara otomatis ke pengguna berdasarkan versi aplikasi asli mereka
• Mencegah perubahan yang mengganggu dari mencapai versi aplikasi yang tidak kompatibel
• Mengelola versi aplikasi berbeda secara bersamaan tanpa logika yang kompleks
• Mengeluarkan pembaruan ke segmen pengguna tertentu

Mengapa Target Versi Penting (Terutama untuk Pengguna AppFlow)

Jika Anda sudah familiar dengan Ionic AppFlow, Anda tahu betapa pentingnya memastikan pengguna hanya menerima update yang kompatibel. AppFlow secara otomatis mematching bundle update hidup ke versi aplikasi native, mencegah JavaScript tidak kompatibel yang disampaikan ke versi native code.

Capgo menyediakan jaminan keamanan yang sama, dengan fitur tambahan:

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

Pendekatan ini sangat berguna ketika:

• Anda memiliki pengguna di berbagai versi utama aplikasi Anda (misalnya, v1.x, v2.x, v3.x)
• Anda perlu menjaga kompatibilitas mundur saat mengeluarkan perubahan yang memecah belah
• Anda ingin mencegah bundle yang lebih baru memecah versi 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

Cara Kerja

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

1. Keterbatasan Versi Native: Mencegah bundle dari tidak dapat disampaikan ke versi native yang tidak kompatibel
2. Rute Berdasarkan SaluranRutekan versi aplikasi yang berbeda ke saluran pembaruan yang berbeda
3. Pengendalian Versi SemantikAutomatis Blokir Pembaruan di Batas Major/Minor/Patch
4. Pengaturan Level PerangkatTargetkan perangkat atau kelompok pengguna tertentu

Alur Pembaruan 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]

Judul bagian “Strategi 1: Rutekan Versi Berdasarkan Saluran”

pendekatan yang direkomendasikan Salinan ke clipboard 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 yang memecah) → v2 saluran
• App 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: true,
      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: true,
      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: true,
      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 mereka. Tidak ada perubahan JavaScript code yang diperlukan!

Manfaat

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

Strategi 2: Kontrol Pembaruan Versi Semantik

Gunakan Capgo’s kontrol pembaruan versi semantik bawaan untuk mencegah pembaruan di batas-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 aplikasi versi 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

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

Pengaturan Versi Semantik Diperlukan

"semver" untuk versi aplikasi Anda. Pastikan nomor versi Anda mengikuti MAJOR.MINOR.PATCH format.

Strategi 3: Konstrain Versi Natively

Tentukan versi native minimum yang diperlukan untuk bundle untuk mencegah pengiriman ke perangkat yang tidak kompatibel.

Menggunakan kondisi penundaan versi native

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"

Bagaimana Cara Kerjanya

Perangkat pada versi asli 1.x TIDAK akan menerima paket 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. Pembaruan Native API yang Berubah-ubah

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

Strategi 4: Pencegahan Downgrade Otomatis

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

Aktifkan di Pengaturan Saluran

Dalam dashboard Capgo:

1. Pergi ke Saluran Pilih saluran Anda
2. Mengaktifkan “Nonaktifkan auto downgrade di bawah native”
3. Simpan perubahan

Atau melalui CLI:

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

Contoh

• Perangkat pengguna: Versi native 1.2.5
• Bundel saluran: Versi 1.2.3
• Hasil: Perbarui diblokir (akan menjadi penurunan versi)

Ini berguna ketika:

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

Strategi 5: Targeting Perangkat

Tetapkan pengaturan saluran untuk perangkat atau kelompok pengguna tertentu

Tetapkan Versi Spesifik untuk Uji Coba

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

Dalam Capgo dashboard:

1. Pergi ke Perangkat → Temukan perangkat
2. Klik Atur Saluran atau Atur Versi Paket
3. Atur saluran atau versi paket tertentu untuk menggantikan sumber update
4. Perangkat akan menerima update dari sumber yang di-overriden

Menguji Update

Gunakan pengaturan perangkat untuk menguji update di perangkat Anda sendiri sebelum mengimplementasikannya untuk semua pengguna.

Alur Kerja Penuh AppFlow

Berikut adalah 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: true,
      defaultChannel: 'production',
    }
  }
};

2. Rilis Perubahan Break (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: true,
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Kirim Perbarui ke Versi Berdua

# 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
• Tingkat adopsi bundle per versi
• Kerusakan atau crash per versi

5. Menghapus 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 sebagai berikut:

1. Override Perangkat (Dashboard atau API) - Prioritas tertinggi
2. Override Cloud melalui setChannel() menghubungi
3. Saluran Default di capacitor.config.ts
4. Saluran Default (Pengaturan Cloud) - Prioritas terendah

Contoh Precedensi

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

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

Perbandingan dengan Ionic AppFlow

Untuk tim yang bermigrasi dari Ionic AppFlow, here’s how Capgo’s version targeting compares:

Fitur	Ionic AppFlow	Capgo
Versi berbasis	Otomatis berdasarkan versi native	Otomatis melalui defaultChannel + beberapa strategi
Pengaturan versi semantik	Support dasar	Maju dengan --disable-auto-update (maju/kecil/perbaikan)
Keterbatasan versi native	Konfigurasi manual di dashboard AppFlow	Dibangun-in --native-version tanda bendera di CLI
Pengelolaan saluran	UI Web + CLI	UI Web + CLI + API
Pengaturan perangkat	Kontrol perangkat terbatas	Kontrol penuh melalui Dashboard/API
Preventi penurunan otomatis	Yes	Ya melalui --disable-downgrade
Pemeliharaan multi-versi	Pengelolaan cabang/tujuan manual	Dengan otomatisasi berdasarkan prioritas tujuan
Penghosan sendiri	No	Ya (pengendalian penuh)
Analisis versi	Dasar	Metrik per-versi rinci

Keseimbangan AppFlow dan Lebih Lanjut

Capgo menyediakan kemampuan semua versi yang ditargetkan fitur AppFlow yang ditawarkan, plus mekanisme kontrol tambahan. Jika Anda bergantung pada pencocokan versi otomatis AppFlow, Anda akan menemukan Capgo sama amannya dengan lebih fleksibilitas.

Pengembangan Masalah

Pengguna Tidak Menerima Perbaruan

Periksa hal-hal berikut:

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

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

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

   • Dashboard → Bundle → Periksa kolom "Versi Asli"

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

   npx @capgo/cli channel list

4. Override Perangkat: Periksa apakah perangkat memiliki override manual

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

Paket Diterima Versi Salah

1. Review defaultChannel: Pastikan saluran yang benar dalam capacitor.config.ts
2. Periksa Unggah Paket: Pastikan paket telah diunggah ke saluran yang dimaksudkan
3. Periksa Versi Nativ: Konfirmasi --native-version Pergunakan Flag dengan Benar

Perubahan Mendasar yang Mempengaruhi Versi Lama

1. Perbaikan Langsung: Mengatur ulang perangkat yang terpengaruh ke bundle aman
   • Dashboard → Perangkat → Pilih banyak → Set Versi
2. Pemecahan Jangka Panjang: Buat saluran yang versi dan jaga cabang yang terpisah
3. Pencegahan: Selalu tes update 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

AppFlow Konsep	Capgo Sama	Catatan
Saluran Deploy	Capgo Saluran	Konsep yang sama, lebih kuat
Versi Asli Lock	--native-version Bendera	Kontrol yang lebih terperinci
Prioritas Saluran	Precedence Saluran (override → cloud → default)	Transparansi lebih baik
Tujuan Pengembangan	Kontrol + semver	Banyak Strategi Tersedia
Saluran Produksi	production saluran (atau nama apa saja)	Penamaan Fleksibel
Pengembangan Berbasis Git	CLI unggah bundle dari cabang	Alur Kerja yang Sama
Pembaruan Otomatis yang Sesuai	defaultChannel Konstrain Versi +	Diperkuat dengan beberapa strategi

Perbedaan Utama untuk Pengguna AppFlow

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

Langkah-Langkah Pemindahan

1. Peta saluran AppFlow 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 pemblokiran otomatis di batas versi
4. Unggah bundle spesifik versi dengan --native-version flag
5. Tampilkan distribusi versi di Capgo dashboard

Petunjuk Pindah Lengkap

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

Polanya 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 Berbagai 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 versi spesifik:

1. Pengaturan Saluran: Pemisahan versi otomatis melalui defaultChannel
2. Pengaturan Versi Semantik: Mencegah update di batas-batas mayor/minor/patch
3. Keterbatasan Versi AsliMinta versi native minimum untuk bundle
4. Pencegahan Downgrade OtomatisTidak pernah kirim bundle yang lebih tua ke versi native yang lebih baru
5. Pengaturan PerangkatKontrol manual untuk pengujian dan target

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

• Panduan Perubahan Break - Strategi versi saluran rinci
• Manajemen Saluran - Referensi konfigurasi saluran lengkap
• Pengaturan Update - Keterlambatan dan kondisi versi asli