Event

Plugin Capacitor Updater menyediakan beberapa event yang bisa Anda pantau untuk memonitor proses update dan merespons berbagai status yang ada.

Setup Event Listener

Untuk mendengarkan event, gunakan addListener method pada CapacitorUpdater object:

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

// Add a listener
const listener = await CapacitorUpdater.addListener('eventName', (event) => {
  // Handle the event
});

// Remove the listener when no longer needed
listener.remove();

// Remove all listeners
await CapacitorUpdater.removeAllListeners();

Event yang Tersedia

download

Dipicu selama proses download bundle. Menyediakan informasi progres download.

CapacitorUpdater.addListener('download', (event) => {
  console.log(`Download progress: ${event.percent}%`);
  console.log('Bundle info:', event.bundle);
});

Data Event:

• percent: number - Persentase progres download (0-100)
• bundle: BundleInfo - Informasi mengenai bundle yang sedang didownload

Catatan

Event ini dipicu beberapa kali selama proses download untuk melaporkan progres.

noNeedUpdate

Dipicu saat pengecekan update menentukan bahwa tidak ada update yang diperlukan.

CapacitorUpdater.addListener('noNeedUpdate', (event) => {
  console.log('App is up to date');
  console.log('Current bundle:', event.bundle);
});

Data Event:

• bundle: BundleInfo - Informasi tentang bundle saat ini

updateAvailable

Dipicu saat update baru tersedia untuk didownload.

CapacitorUpdater.addListener('updateAvailable', (event) => {
  console.log('Update available');
  console.log('New bundle:', event.bundle);
  // You can trigger a download here if needed
});

Data Event:

• bundle: BundleInfo - Informasi tentang bundle update yang tersedia

downloadComplete

Dipicu saat download bundle berhasil diselesaikan.

CapacitorUpdater.addListener('downloadComplete', (event) => {
  console.log('Download completed');
  console.log('Downloaded bundle:', event.bundle);
  // You might want to set this bundle as next
});

Data Event:

• bundle: BundleInfo - Informasi tentang bundle yang telah didownload

majorAvailable

Dipicu saat update major tersedia namun terhalang pengaturan auto-update.

CapacitorUpdater.addListener('majorAvailable', (event) => {
  console.log('Major update available:', event.version);
  // Notify user about major update
});

Data Event:

• version: string - Nomor versi dari update major

Tips

Update major biasanya butuh konfirmasi user atau update via app store. Gunakan event ini untuk memberi notifikasi ke user.

updateFailed

Dipicu saat update gagal diinstal pada saat app dijalankan berikutnya.

CapacitorUpdater.addListener('updateFailed', (event) => {
  console.error('Update failed to install');
  console.log('Failed bundle:', event.bundle);
  // Handle rollback or retry logic
});

Data Event:

• bundle: BundleInfo - Informasi mengenai bundle yang gagal diinstal

downloadFailed

Dipicu saat proses download bundle gagal.

CapacitorUpdater.addListener('downloadFailed', (event) => {
  console.error('Download failed for version:', event.version);
  // Handle download retry logic
});

Data Event:

• version: string - Versi yang gagal diunduh

appReloaded

Dipicu saat aplikasi dimuat ulang.

CapacitorUpdater.addListener('appReloaded', () => {
  console.log('App has been reloaded');
  // Perform any necessary reinitialization
});

Data Event: Tidak ada

appReady

Dipicu saat aplikasi siap digunakan setelah update.

CapacitorUpdater.addListener('appReady', (event) => {
  console.log('App is ready');
  console.log('Current bundle:', event.bundle);
  console.log('Status:', event.status);
});

Data Event:

• bundle: BundleInfo - Informasi tentang bundle saat ini
• status: string - status ready

Peringatan

Ingat untuk memanggil notifyAppReady() dalam batas timeout yang dikonfigurasi (default 10 detik) untuk mencegah rollback otomatis.

Objek BundleInfo

Banyak event menyertakan BundleInfo objek dengan properti berikut:

interface BundleInfo {
  id: string;           // Unique bundle identifier
  version: string;      // Bundle version
  downloaded: string;   // Download timestamp
  checksum?: string;    // Bundle checksum (if available)
  status: BundleStatus; // Bundle status
}

Di mana BundleStatus bisa berupa:

• 'success' - Bundle berhasil diunduh
• 'error' - Gagal mengunduh/menginstal bundle
• 'pending' - Bundle menunggu untuk dijadikan versi berikutnya
• 'downloading' - Bundle is currently downloading

Contoh: Alur Update Lengkap

Berikut adalah contoh menangani alur update lengkap menggunakan event:

Peringatan

Ini UpdateManager class tidak menyertakan CapacitorUpdater.notifyAppReady() call yang diperlukan untuk alur auto-update. Silakan lihat cara memanggil notifyAppReady dengan benar dokumentasi untuk info lebih lanjut.

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

export class UpdateManager {
  private listeners: any[] = [];

  async setupListeners() {
    // Listen for available updates
    this.listeners.push(
      await CapacitorUpdater.addListener('updateAvailable', async (event) => {
        console.log('Update available:', event.bundle.version);
        // Auto-download the update
        await CapacitorUpdater.download({
          url: event.bundle.url,
          version: event.bundle.version
        });
      })
    );

    // Monitor download progress
    this.listeners.push(
      await CapacitorUpdater.addListener('download', (event) => {
        console.log(`Downloading: ${event.percent}%`);
        // Update UI progress bar
        this.updateProgressBar(event.percent);
      })
    );

    // Handle download completion
    this.listeners.push(
      await CapacitorUpdater.addListener('downloadComplete', async (event) => {
        console.log('Download complete:', event.bundle.version);
        // Set as next bundle
        await CapacitorUpdater.next({ id: event.bundle.id });
      })
    );

    // Handle failures
    this.listeners.push(
      await CapacitorUpdater.addListener('downloadFailed', (event) => {
        console.error('Download failed:', event.version);
        this.showError('Update download failed. Please try again later.');
      })
    );

    this.listeners.push(
      await CapacitorUpdater.addListener('updateFailed', (event) => {
        console.error('Update installation failed:', event.bundle.version);
        this.showError('Update installation failed. The app has been rolled back.');
      })
    );

    // Handle app ready
    this.listeners.push(
      await CapacitorUpdater.addListener('appReady', async (event) => {
        console.log('App ready with bundle:', event.bundle.version);
      })
    );
  }

  cleanup() {
    // Remove all listeners when no longer needed
    this.listeners.forEach(listener => listener.remove());
    this.listeners = [];
  }

  private updateProgressBar(percent: number) {
    // Update your UI progress bar
  }

  private showError(message: string) {
    // Show error to user
  }
}

Praktik Terbaik

1. Selalu panggil notifyAppReady(): Saat menggunakan auto-update, selalu panggil method ini setelah app inisialisasi untuk mencegah rollback.

2. Tangani kegagalan dengan baik: Implementasikan error handling yang tepat untuk kegagalan download dan update.

3. Berikan feedback ke user: Gunakan event download progress untuk menampilkan progres update ke user.

4. Bersihkan listener: Hapus event listener saat sudah tidak diperlukan untuk mencegah memory leak.

5. Uji skenario update: Uji berbagai skenario update termasuk kegagalan, rollback, dan update besar.

Lanjutkan dari Events

Jika Anda menggunakan Event 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.