Events

Il plug-in Capacitor Updater fornisce diversi eventi che puoi ascoltare per monitorare il processo di aggiornamento e rispondere a diversi stati.

Configurazione del listener di eventi

Per ascoltare gli eventi, utilizzare il metodo addListener sull’oggetto CapacitorUpdater:

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

Eventi disponibili

download

Attivato durante il processo di download del bundle. Fornisce informazioni sullo stato di avanzamento del download.

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

Dati evento:

• percent: numero - Percentuale di avanzamento del download (0-100)
• bundle: BundleInfo: informazioni sul pacchetto in fase di download

Nota

Questo evento si attiva più volte durante il download per segnalare l’avanzamento.

noNeedUpdate

Attivato quando un controllo degli aggiornamenti determina che non è necessario alcun aggiornamento.

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

Dati evento:

• bundle: BundleInfo - Informazioni sul pacchetto corrente

updateAvailable

Attivato quando un nuovo aggiornamento è disponibile per il download.

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

Dati evento:

• bundle: BundleInfo: informazioni sul pacchetto di aggiornamenti disponibile

downloadComplete

Attivato quando il download di un bundle è stato completato correttamente.

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

Dati evento:

• bundle: BundleInfo: informazioni sul pacchetto scaricato

majorAvailable

Attivato quando è disponibile un aggiornamento importante ma bloccato dalle impostazioni di aggiornamento automatico.

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

Dati evento:

• version: string - Il numero di versione dell’aggiornamento principale

Suggerimento

Gli aggiornamenti principali in genere richiedono la conferma dell’utente o gli aggiornamenti dell’app store. Utilizza questo evento per avvisare gli utenti in modo appropriato.

updateFailed

Viene attivato quando non è possibile installare un aggiornamento al successivo avvio dell’app.

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

Dati evento:

• bundle: BundleInfo: informazioni sul pacchetto la cui installazione non è riuscita

downloadFailed

Attivato quando il download di un bundle non è riuscito.

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

Dati evento:

• version: string - La versione il cui download non è riuscito

appReloaded

Attivato quando l’app è stata ricaricata.

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

Dati evento: Nessuno

appReady

Attivato quando l’app è pronta per l’uso dopo un aggiornamento.

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

Dati evento:

• bundle: BundleInfo - Informazioni sul pacchetto corrente
• status: stringa - Lo stato pronto

Attenzione

Ricordarsi di chiamare notifyAppReady() entro il timeout configurato (10 secondi predefiniti) per impedire il rollback automatico.

Oggetto BundleInfo

Molti eventi includono un oggetto BundleInfo con le seguenti proprietà:

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
}

Dove BundleStatus può essere:

• 'success' - Pacchetto scaricato con successo
• 'errore' - Download/installazione del pacchetto non riuscito
• 'in sospeso' - Il pacchetto è in sospeso per essere impostato come successivo
• 'download in corso' - Il pacchetto è attualmente in download

Esempio: flusso di aggiornamento completo

Ecco un esempio di gestione del flusso di aggiornamento completo con eventi:

Attenzione

Questa classe UpdateManager non include la chiamata CapacitorUpdater.notifyAppReady() richiesta per il flusso di aggiornamento automatico. Per ulteriori informazioni, consulta la documentazione su effettuare correttamente la chiamata notifyAppReady.

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

Migliori pratiche1. Chiama sempre notifyAppReady(): quando utilizzi l’aggiornamento automatico, chiama sempre questo metodo dopo l’inizializzazione dell’app per evitare il rollback.

2. Gestire gli errori con garbo: implementare una corretta gestione degli errori per gli errori di download e aggiornamento.

3. Fornisci feedback agli utenti: utilizza l’evento di avanzamento del download per mostrare agli utenti l’avanzamento dell’aggiornamento.

4. Pulisci i listener: rimuovi i listener di eventi quando non sono più necessari per evitare perdite di memoria.

5. Testare scenari di aggiornamento: testare vari scenari di aggiornamento inclusi errori, rollback e aggiornamenti principali.