Ereignisse

Der Capacitor-Updater-Plugin bietet mehrere Ereignisse, die Sie zum Überwachen des Update-Prozesses und zum Reagieren auf verschiedene Zustände abonnieren können.

Ereignis-Listener-Einrichtung

Um auf Ereignisse zuzuhören, verwenden Sie 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 Ereignisse

download

Wird während des Bundle-Download-Prozesses ausgelöst. Bietet Informationen zum Download-Progress bereit.

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

Ereignisdaten:

• percentAnzahl: - Download-Progress (0-100)
• bundleBundleInfo - Informationen über das heruntergeladene Bundle

Hinweis

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

noNeedUpdate

Bei einem Check auf Aktualisierungen wird festgestellt, dass keine Aktualisierung erforderlich ist.

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

Event-Daten:

• bundleBundleInfo - Informationen über das aktuelle Bundle

updateAvailable

Bei einer neuen Aktualisierung ist ein Download verfügbar.

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

Ereignisdaten:

• bundle: BundleInfo - Informationen über das verfügbare Updatepaket

downloadComplete

Ausgelöst, wenn ein Updatepaket erfolgreich heruntergeladen wurde.

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

Ereignisdaten:

• bundle: BundleInfo - Informationen über das heruntergeladene Updatepaket

majorAvailable

Ausgelöst, wenn ein großer Update verfügbar ist, aber durch die Einstellungen für automatische Updates blockiert wird.

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

Ereignisdaten:

• version : string - Die Versionsnummer der großen Aktualisierung

Tip

Große Aktualisierungen erfordern in der Regel die Bestätigung des Benutzers oder App-Store-Aktualisierungen. Verwenden Sie diesen Ereignis, um die Benutzer entsprechend zu benachrichtigen.

updateFailed

Ausgelöst, wenn eine Aktualisierung zum Installieren fehlschlägt, wenn die Anwendung am nächsten Mal gestartet wird.

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

Ereignisdaten:

• bundle: BundleInfo - Informationen über das Bundle, das nicht installiert werden konnte

downloadFailed

Ausgelöst, wenn ein Bundle heruntergeladen wird.

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

Ereignisdaten:

• version: string - Die Version, die nicht heruntergeladen werden konnte

appReloaded

Ausgelöst, wenn die App neu geladen wurde

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

Ereignisdaten: Keine

appReady

Ausgelöst, wenn die App nach einem Update bereit zum Einsatz ist

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

Ereignisdaten:

• bundle: BundleInfo - Informationen über die aktuelle Bundle
• statusStatus: string - Die Bereitschaftsstatus

Vorsicht

Denken Sie daran, notifyAppReady() innerhalb der konfigurierten Zeitüberschreitung (Standard 10 Sekunden) zu verhindern, dass eine automatische Rückschaltung erfolgt.

BundleInfo-Objekt

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

Wo BundleStatus kann sein:

• 'success' - Bundle wurde erfolgreich heruntergeladen
• 'error' - Bundle-Download/Installation fehlgeschlagen
• 'pending' - Bundle steht zur nächsten Verwendung bereit
• 'downloading' - Bundle wird gerade heruntergeladen

Beispiel: Vollständiger Update-Flow

Hier ist ein Beispiel für die Behandlung des vollständigen Update-Flows mit Ereignissen:

Vorsicht

Dies UpdateManager dieses Klassen enthält nicht die CapacitorUpdater.notifyAppReady() Aufruf erforderlich für den automatischen Update-Flow. Bitte sehen Sie sich die Platzieren Sie die notifyAppReady-Aufruf korrekt. 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
  }
}

Gute Praktiken

1. Rufen Sie immer auf notifyAppReady()Wenn Sie die automatische Aktualisierung verwenden, rufen Sie diese Methode immer nach der Initialisierung Ihrer App auf, um einen Rollover zu vermeiden.

2. Fehler verantwortungsvoll handhabenImplementieren Sie eine ordnungsgemäße Fehlerbehandlung für Download- und Aktualisierungsfehler.

3. Bieten Sie Benutzerfeedback anVerwenden Sie das Download-Progressereignis, um dem Benutzer den Aktualisierungsfortschritt anzuzeigen.

4. Löschen Sie die Listener: Entferne Ereignis-Listener, wenn sie nicht mehr benötigt werden, um Speicherlecks zu vermeiden.

5. Testupdate-Szenarien: Test verschiedene Update-Szenarien einschließlich Fehlschlägen, Rückschritten und großen Updates.