Targeting Versi

Panduan ini menjelaskan cara mengirimkan bundle terbaru yang kompatibel secara otomatis ke pengguna berdasarkan versi native app mereka, mirip dengan pendekatan Ionic AppFlow. Ini memastikan manajemen update yang lebih simpel dan rollout yang lebih cepat sekaligus mencegah masalah kompatibilitas.

Migrasi dari Ionic AppFlow?

Jika Anda beralih dari Ionic AppFlow, panduan ini sangat penting untuk Anda. AppFlow otomatis mencocokkan update dengan versi native, dan Capgo menyediakan kemampuan yang sama dengan kontrol dan fleksibilitas lebih besar. Lihat Panduan Migrasi AppFlow untuk petunjuk migrasi langkah demi langkah.

Ikhtisar

Dengan sistem version targeting Capgo, Anda dapat:

• Mengirimkan update yang kompatibel secara otomatis ke pengguna berdasarkan versi native app mereka
• Mencegah breaking changes sampai ke versi app yang tidak kompatibel
• Mengelola banyak versi app secara bersamaan tanpa logika yang rumit
• Rilis update dengan mulus ke segmen pengguna tertentu

Mengapa Version Targeting Penting (Terutama untuk Pengguna AppFlow)

Jika Anda sudah familiar dengan Ionic AppFlow, Anda tahu betapa pentingnya memastikan pengguna hanya menerima update yang kompatibel. AppFlow otomatis mencocokkan bundle live update dengan versi app native, mencegah JavaScript yang tidak kompatibel terkirim ke code native yang lebih lama.

Capgo memberikan jaminan keamanan yang sama, dengan fitur tambahan:

• Kontrol lebih granular atas version matching
• Berbagai strategi (channels, semver, native constraints)
• Visibilitas distribusi versi yang lebih baik
• API dan CLI dikontrol bersama manajemen dashboard

Pendekatan ini sangat berguna saat:

• User Anda menggunakan versi utama app yang berbeda (misal: v1.x, v2.x, v3.x)
• Anda perlu menjaga backward compatibility saat merilis breaking changes
• Anda ingin mencegah bundle baru merusak code native yang lama
• Anda sedang melakukan migrasi user secara bertahap antar versi
• Anda sedang migrasi dari AppFlow dan ingin menjaga tingkat keamanan update yang sama

Cara Kerjanya

Capgo menggunakan pendekatan multi-layer untuk mencocokkan user dengan update yang kompatibel:

1. Batasan Versi Native: Mencegah bundle dikirim ke versi native yang tidak kompatibel
2. Routing berbasis channel: Arahkan versi aplikasi yang berbeda ke channel update yang berbeda
3. Kontrol Semantic Versioning: Blokir update secara otomatis pada batas major/minor/patch
4. Override per perangkat: Targetkan perangkat atau grup 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: Routing Versi Berbasis Channel

Ini adalah pendekatan yang direkomendasikan untuk mengelola breaking changes dan update versi mayor. Mirip dengan model delivery AppFlow.

Contoh Skenario

• Aplikasi v1.x (100.000 pengguna) → production channel
• App v2.x (50.000 pengguna dengan breaking changes) → v2 channel
• Aplikasi v3.x (10.000 beta user) → v3 channel

Implementasi

Langkah 1: Konfigurasi Channel untuk Setiap Versi Major

// 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 Channel

# 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: Upload Bundle Spesifik 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

Routing Otomatis

Saat pengguna membuka aplikasi, mereka akan otomatis terhubung ke channel yang ditentukan berdasarkan defaultChannel di dalam bundle aplikasi yang terinstal. Tidak perlu ada perubahan JavaScript code!

Keuntungan

• Nol perubahan code - Routing channel berjalan otomatis
• Pemisahan yang jelas - Setiap versi punya pipeline update sendiri
• Targeting yang fleksibel - Push update ke grup versi tertentu
• Rollout yang aman - Breaking changes tidak akan mencapai versi yang tidak kompatibel

Strategi 2: Kontrol Semantic Versioning

Gunakan fitur bawaan Capgo kontrol semantic versioning untuk mencegah update lintas batas versi.

Nonaktifkan Auto-Update Antar Versi Major

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

• User pada versi aplikasi 1.2.3 akan menerima update hingga 1.9.9
• User tidak akan TIDAK menerima versi 2.0.0 secara otomatis
• Mencegah breaking changes mencapai code native lama
• Perbandingan menggunakan baseline 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

Wajib Menggunakan Semantic Versioning

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

Strategi 3: Batasan Versi Native

Tentukan versi minimum aplikasi native (min_update_version) pada setiap bundle agar Capgo hanya mengirimkannya ke perangkat dengan binary native yang cukup baru.

Ini menggunakan channel metadata strategi (--disable-auto-update metadata) ditambah --min-update-version atau --auto-min-update-version saat upload. Tidak ada --native-version flag CLI.

Aktifkan penargetan metadata pada channel

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

Atur versi native minimum saat upload

Saat mengunggah bundle, tentukan versi native terendah yang boleh menerimanya:

# 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 batas minimum berdasarkan kompatibilitas package native:

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

Cara Kerjanya

Dengan strategi metadata, perangkat yang baseline native-nya (version_build) berada di bawah baseline bundle min_update_version akan melewati update. Hanya perangkat pada versi tersebut atau lebih tinggi yang menerimanya. Lihat Kompatibilitas untuk --auto-min-update-version detailnya.

Kasus Penggunaan

1. Native Plugin 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. Perubahan Breaking Native API

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

3. Migrasi Bertahap

   # 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 Auto-Downgrade

Cegah pengguna menerima bundle yang lebih lama dari versi native mereka saat ini.

Aktifkan di Pengaturan Channel

Di dashboard Capgo:

1. Buka Channel → Pilih channel Anda
2. Aktifkan “Nonaktifkan auto downgrade pada native”
3. Simpan perubahan

Atau via CLI:

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

Contoh

• Perangkat user: Versi Native 1.2.5
• Bundle channel: Versi 1.2.3
• Hasil: Update diblokir (akan menjadi downgrade)

Ini berguna saat:

• User menginstal versi lebih baru secara manual dari app store
• Anda perlu memastikan user selalu mendapat patch keamanan terbaru
• Anda ingin mencegah bug regresi

Strategi 5: Targeting Tingkat Perangkat

Override penentuan channel untuk perangkat atau grup user tertentu.

Paksa Versi Spesifik untuk 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' })
  }
}

Override Device di Dashboard

Di dashboard Capgo:

1. Buka Perangkat → Cari device
2. Klik Atur Channel atau Atur Versi
3. Override dengan channel atau versi bundle tertentu
4. Device akan menerima update dari sumber yang di-override

Testing Update

Gunakan device overrides untuk mengetes update di perangkat sendiri sebelum dirilis ke semua user.

Workflow Lengkap ala AppFlow

Berikut adalah contoh lengkap yang menggabungkan semua strategi:

1. Setup Awal (App 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

capacitor.config.ts

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

2. Rilis Breaking Change (App 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. Push Update ke Kedua Versi

# 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

Gunakan dashboard Capgo untuk melacak:

• Berapa banyak user di v1 vs v2
• Tingkat adopsi bundle per versi
• Error atau crash per versi

5. Deprecate versi lama

Setelah penggunaan v1 turun di bawah threshold:

# 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

Jika ada beberapa konfigurasi channel, Capgo menggunakan urutan prioritas ini:

1. Override Perangkat (Dashboard atau API) - Prioritas tertinggi dan muncul di UI Device Override
2. Channel plugin lokal melalui setChannel() - Hanya tersimpan di perangkat dan tidak muncul di UI Device Override
3. defaultChannel di capacitor.config.ts
4. Channel Default (Pengaturan Cloud) - Prioritas terendah

Contoh Precedence

Jika aplikasi user memiliki defaultChannel: 'v2' tapi Anda melakukan override perangkat ke 'beta' di dashboard, mereka akan menerima update dari 'beta' channel.

UI Device Override hanya menampilkan override yang diatur dari dashboard atau Public API. Memanggil setChannel() dari aplikasi akan memvalidasi channel ke backend, lalu menyimpannya secara lokal di perangkat.

Praktik Terbaik

1. Selalu Set defaultChannel untuk Major Versions

// ✅ 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 Semantic Versioning

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Kelola Branch 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 Rollout

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

Cek dashboard Anda secara rutin:

• Apakah user beralih ke versi native terbaru?
• Apakah versi lama masih menerima trafik tinggi?
• Haruskah Anda menghentikan channel lama?

Perbandingan dengan Ionic AppFlow

Bagi tim yang bermigrasi dari Ionic AppFlow, berikut perbandingan version targeting Capgo:

Fitur	Ionic AppFlow	Capgo
Routing berbasis versi	Otomatis berdasarkan versi native	Otomatis via defaultChannel + berbagai strategi
Versioning semantik	Dukungan dasar	Lanjutan dengan --disable-auto-update (major/minor/patch)
Batasan versi native	Konfigurasi manual di dashboard AppFlow	Bawaan --min-update-version / --auto-min-update-version dengan metadata channels
Manajemen channel	Web UI + CLI	Web UI + CLI + API
Override perangkat	Kontrol terbatas di level device	Kontrol penuh via Dashboard/API
Pencegahan auto-downgrade	Ya	Ya, via --no-downgrade
Maintenance multi-versi	Manajemen branch/channel manual	Otomatis dengan channel precedence
Self-hosting	Tidak	Ya (kontrol penuh)
Analitik versi	Dasar	Metrik detail per versi

Paritas AppFlow dan Lebih

Capgo menyediakan semua kemampuan targeting versi yang ditawarkan AppFlow, ditambah mekanisme kontrol tambahan. Jika Anda mengandalkan automatic version matching dari AppFlow, Capgo sama amannya dengan fleksibilitas lebih tinggi.

Pemecahan Masalah

User Tidak Menerima Update

Periksa hal berikut:

1. Penetapan Channel: Pastikan device berada di channel yang benar

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

2. Version Constraints: Cek apakah bundle memiliki persyaratan native version

   • Dashboard → Bundles → Cek kolom “Native Version”

3. Pengaturan Semver: Verifikasi channel disable-auto-update pengaturan

   npx @capgo/cli channel list

4. Override Perangkat: Cek apakah perangkat menggunakan manual override

   • Dashboard → Devices → Cari perangkat → Cek channel/versi

Bundle Terkirim ke Versi yang Salah

1. Tinjau defaultChannel: Pastikan channel sudah benar capacitor.config.ts
2. Cek Bundle Upload: Verifikasi bundle diunggah ke channel yang dituju
3. Inspeksi min update version: Konfirmasi --min-update-version (atau --auto-min-update-version) telah diatur dan channel menggunakan --disable-auto-update metadata

Breaking Changes yang Memengaruhi Versi Lama

1. Solusi Cepat: Paksa perangkat yang terdampak ke bundle aman
   • Dashboard → Devices → Pilih banyak → Set Version
2. Solusi Jangka Panjang: Buat versioned channels dan kelola branch terpisah
3. Pencegahan: Selalu uji update pada perangkat representatif sebelum rollout

Migrasi dari Ionic AppFlow

Jika Anda bermigrasi dari Ionic AppFlow, version targeting bekerja sangat mirip di Capgo, dengan fleksibilitas yang lebih baik:

Pemetaan Konsep

Konsep AppFlow	Ekuivalen Capgo	Catatan
Deploy Channel	Channel Capgo	Konsep sama, lebih powerful
Kunci Versi Native	--min-update-version / --auto-min-update-version	Kontrol lebih granular
Prioritas Channel	Precedence channel (override → cloud → default)	Precedence lebih transparan
Target Deployment	Kontrol Channel + semver	Tersedia berbagai strategi
Channel Produksi	production channel (atau nama apa pun)	Penamaan fleksibel
Deployment berbasis Git	upload CLI bundle dari branch	Workflow yang sama
Pencocokan versi otomatis	defaultChannel + batasan versi	Ditingkatkan dengan berbagai strategi

Perbedaan Utama bagi Pengguna AppFlow

1. Kontrol Lebih Besar: Capgo memberi Anda berbagai strategi (channels, semver, native version) yang bisa dikombinasikan
2. Visibilitas Lebih Baik: Dashboard menampilkan distribusi versi dan masalah kompatibilitas
3. Akses API: Kontrol programatik penuh atas targeting versi
4. Hosting Sendiri: Opsi menjalankan server update sendiri dengan logika versi yang sama

Langkah Migrasi

1. Petakan channel AppFlow Anda ke channel Capgo (biasanya 1:1)
2. Atur defaultChannel di capacitor.config.ts untuk setiap versi mayor
3. Konfigurasi aturan semver jika ingin pemblokiran otomatis pada batas versi
4. Upload bundle spesifik versi menggunakan --min-update-version (channel harus menggunakan strategi metadata)
5. Pantau distribusi versi di dashboard Capgo

Panduan Migrasi Lengkap

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

Pola Lanjutan

Gradual Rollout per 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' })
  }
}

Feature Flags per 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()
  }
}

A/B Testing Antar 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 berbagai strategi pengiriman update spesifik versi:

1. Routing berbasis channel: Pemisahan versi otomatis via defaultChannel
2. Semantic Versioning: Mencegah update antar batas major/minor/patch
3. Batasan Versi Native: Syarat minimum versi native untuk bundle
4. Pencegahan Auto-Downgrade: Tidak akan mengirim bundle lama ke versi native baru
5. Override Perangkat: Kontrol manual untuk testing dan targeting

Dengan menggabungkan strategi ini, Anda bisa mendapatkan pengiriman update otomatis ala AppFlow dengan fleksibilitas dan kontrol yang lebih tinggi. Pilih pendekatan yang paling sesuai dengan workflow versioning dan deployment aplikasi Anda.

Untuk detail lebih lanjut mengenai fitur spesifik:

• Panduan Breaking Changes - Strategi versioning channel mendalam
• Manajemen Channel - Referensi konfigurasi channel lengkap
• Perilaku Update - Delay dan kondisi Native Build

Lanjutkan dari Version Targeting

Jika Anda menggunakan Targeting Versi untuk merencanakan routing channel dan staged rollout, hubungkan dengan Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Solusi Beta Testing untuk workflow produk di Solusi Beta Testing, dan Solusi Version Targeting untuk workflow produk di Version Targeting Solution.