Events

Das Capacitor Updater-Plugin bietet mehrere Events, auf die du hören kannst, um den Update-Prozess zu überwachen und auf verschiedene Zustände zu reagieren.

Event-Listener einrichten

Um auf Events zu hören, verwende die addListener Methode auf dem CapacitorUpdater Objekt:

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();

Verfügbare Events

download

Wird während des Bundle-Downloads ausgelöst. Liefert Informationen zum Download-Fortschritt.

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

Event-Daten:

• percent: number - Download-Fortschritt in Prozent (0-100)
• bundle: BundleInfo - Informationen zum Bundle, das gerade heruntergeladen wird

Hinweis

Dieses Event wird während des Downloads mehrfach ausgelöst, um den Fortschritt zu melden.

noNeedUpdate

Wird ausgelöst, wenn eine Update-Prüfung ergibt, dass kein Update erforderlich ist.

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

Event-Daten:

• bundle: BundleInfo - Informationen zum aktuellen Bundle

updateAvailable

Wird ausgelöst, wenn ein neues Update zum Download verfügbar ist.

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

Event-Daten:

• bundle: BundleInfo – Infos zum verfügbaren Update-Bundle

downloadComplete

Wird ausgelöst, wenn der Download eines Bundles erfolgreich abgeschlossen wurde.

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

Event-Daten:

• bundle: BundleInfo – Infos zum heruntergeladenen Bundle

majorAvailable

Wird ausgelöst, wenn ein Major-Update verfügbar ist, aber durch die Auto-Update-Einstellungen blockiert wird.

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

Event-Daten:

• version: string – Die Versionsnummer des Major-Updates

Tipp

Major-Updates erfordern meist eine Bestätigung durch den Nutzer oder ein App Store Update. Nutze dieses Event, um Nutzer entsprechend zu informieren.

updateFailed

Wird ausgelöst, wenn die Installation eines Updates beim nächsten App-Start fehlgeschlagen ist.

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

Event-Daten:

• bundle: BundleInfo – Informationen zum Bundle, dessen Installation fehlgeschlagen ist

downloadFailed

Fired when a bundle download has failed.

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

Event-Daten:

• version: string - Die Version, deren Download fehlgeschlagen ist

appReloaded

Wird ausgelöst, wenn die App neu geladen wurde.

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

Event-Daten: Keine

appReady

Wird ausgelöst, wenn die App nach einem Update bereit ist.

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

Event-Daten:

• bundle: BundleInfo - Informationen zum aktuellen Bundle
• status: string - Der Ready-Status

Achtung

Denk daran, aufzurufen notifyAppReady() innerhalb des konfigurierten Timeouts (Standard: 10 Sekunden), um einen automatischen Rollback zu verhindern.

BundleInfo-Objekt

Viele Events enthalten ein BundleInfo Objekt mit den folgenden Eigenschaften:

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
}

Wobei BundleStatus kann sein:

• 'success' - Bundle erfolgreich heruntergeladen
• 'error' - Bundle-Download/-Installation fehlgeschlagen
• 'pending' - Bundle wartet darauf, als nächstes gesetzt zu werden
• 'downloading' - Bundle wird gerade heruntergeladen

Beispiel: Kompletter Update-Flow

Hier ist ein Beispiel, wie man den kompletten Update-Flow mit Events handhabt:

Achtung

Dies UpdateManager die Klasse enthält nicht den CapacitorUpdater.notifyAppReady() Aufruf, der für den Auto-Update-Flow nötig ist. Siehe dazu den den notifyAppReady-Aufruf korrekt platzieren Dokumentation für weitere Informationen.

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
  }
}

Best Practices

1. Immer aufrufen notifyAppReady(): Rufen Sie diese Methode bei Auto-Updates immer nach der App-Initialisierung auf, um Rollbacks zu vermeiden.

2. Fehler sauber abfangen: Implementieren Sie eine ordnungsgemäße Fehlerbehandlung für fehlgeschlagene Downloads und Updates.

3. User Feedback geben: Nutzen Sie das Download-Progress-Event, um den Fortschritt des Updates anzuzeigen.

4. Listener bereinigen: Entferne Event-Listener, wenn sie nicht mehr benötigt werden, um Memory Leaks zu vermeiden.

5. Update-Szenarien testen: Teste verschiedene Update-Szenarien, einschließlich Fehlern, Rollbacks und Major Updates.

Weiterlesen bei Events

Wenn du es nutzt Events Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Verwendung von @capgo/capacitor-updater für die native Funktion in der Verwendung von @capgo/capacitor-updater, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.