Panduan Memulai

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-updater` plugin in my project.

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

npm

bun add @capgo/capacitor-updater
bunx cap sync

yarn

yarn add @capgo/capacitor-updater
bunx cap sync

pnpm

pnpm add @capgo/capacitor-updater
bunx cap sync

bun

bun add @capgo/capacitor-updater
bunx cap sync

Mulai Cepat

Bagi kebanyakan pengguna, kami menyarankan untuk mengikuti panduan Quickstart utama yang mencakup instalasi plugin dan integrasi cloud Capgo.

Panduan memulai ini berfokus pada detail teknis plugin bagi pengguna tingkat lanjut yang ingin memahami mekanisme dasar atau menerapkan self-hosted updates.

Ikhtisar

Plugin Capacitor Updater memungkinkan update over-the-air (OTA) untuk aplikasi Capacitor Anda. Ini memungkinkan Anda mengirim update ke aplikasi tanpa melalui proses review app store.

Cara Kerjanya

1. Unduhan bundle: Plugin mengunduh update bundles (file ZIP yang berisi web assets Anda)
2. Ekstraksi: Bundles diekstrak ke penyimpanan perangkat
3. Hot Reload: Aplikasi beralih ke bundle baru tanpa perlu restart
4. Fallback: Jika update gagal, aplikasi akan kembali ke versi sebelumnya yang stabil

Mode Penggunaan

1. Mode Auto-Update (Direkomendasikan)

Cara termudah menggunakan plugin dengan manajemen update otomatis:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Plugin handles everything automatically
// Configure in capacitor.config.ts

Tambahkan ke capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. Mode Manual

Untuk kontrol lebih lanjut atas proses update:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Download an update
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// Set the bundle (will be used on next app start)
await CapacitorUpdater.set({
  id: bundle.id
});

// Or reload immediately
await CapacitorUpdater.reload();

Konfigurasi Platform

iOS

Tidak perlu konfigurasi tambahan. Plugin langsung bisa digunakan.

Android

Tidak perlu konfigurasi tambahan. Plugin langsung bisa digunakan.

Penggunaan Dasar API

Download Update

import { CapacitorUpdater } from '@capgo/capacitor-updater';

const bundle = await CapacitorUpdater.download({
  url: 'https://example.com/update.zip',
  version: '1.0.1'
});

console.log('Downloaded bundle:', bundle.id);

Jadikan Bundle Aktif

// Set bundle to be used on next app start
await CapacitorUpdater.set({
  id: bundle.id
});

Reload dengan Bundle Baru

// Reload app immediately with new bundle
await CapacitorUpdater.reload();

Daftar Bundle

const { bundles } = await CapacitorUpdater.list();
console.log('Available bundles:', bundles);

Hapus Bundle

await CapacitorUpdater.delete({
  id: 'bundle-id'
});

Ambil Bundle Saat Ini

const { bundle } = await CapacitorUpdater.current();
console.log('Current bundle:', bundle.version);

Event Listeners

Pantau event update:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Listen for download progress
CapacitorUpdater.addListener('download', (info) => {
  console.log('Download progress:', info.percent);
});

// Listen for download completion
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download complete:', bundle.version);
});

// Listen for update failures
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Update failed:', error);
});

// Listen for successful updates
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.version);
});

Opsi Konfigurasi

Konfigurasikan plugin di capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Auto-update settings
      autoUpdate: 'atBackground',
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

      // Stats collection
      statsUrl: 'https://api.example.com/stats',

      // Channel (for Capgo cloud)
      defaultChannel: 'production'
    }
  }
}

Pola Integrasi

Dengan Capgo Cloud

Cara termudah untuk memulai:

// Install the Capgo CLI
bun add -g @capgo/cli

// Login to Capgo
npx @capgo/cli login

// Upload your first bundle
npx @capgo/cli bundle upload

// The plugin auto-updates from Capgo cloud

Lihat panduan Quickstart utama detailnya.

Update Self-Hosted

Host server update Anda sendiri:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

Server Anda harus mengembalikan:

{
  "version": "1.0.1",
  "url": "https://your-server.com/updates/1.0.1.zip"
}

Lihat Mode Self-Hosted untuk detail lengkapnya.

Alur Update Manual

Kontrol penuh atas update:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

async function checkAndUpdate() {
  // Check for updates from your server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Download the update
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notify bundle is ready
  await CapacitorUpdater.notifyAppReady();

  // Set as next version
  await CapacitorUpdater.set({ id: bundle.id });

  // Reload when ready
  await CapacitorUpdater.reload();
}

Praktik Terbaik

• Selalu panggil notifyAppReady() saat aplikasi berhasil dimuat
• Uji update secara menyeluruh sebelum push ke production
• Terapkan error handling yang tepat untuk kegagalan jaringan
• Gunakan nomor versi secara konsisten
• Jaga ukuran bundle tetap kecil agar download lebih cepat
• Pantau tingkat keberhasilan update

Langkah Berikutnya

• Referensi Plugin API - Dokumentasi lengkap API
• Pengaturan Plugin - Semua opsi konfigurasi
• Event - Event update yang tersedia
• Mode Self-Hosted - Jalankan server update sendiri
• Pengembangan Lokal - Test update secara lokal
• Debugging - Panduan troubleshooting

Dukungan

• Masalah Diketahui - Masalah umum dan solusinya
• Diskusi GitHub - Dukungan komunitas
• Discord - Chat real-time

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-updater untuk fitur native di bagian Menggunakan @capgo/capacitor-updater, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.