Eventi

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Il plugin Capacitor Updater mette a disposizione diversi eventi che puoi ascoltare per monitorare il processo di aggiornamento e reagire ai vari stati.

Configurazione Event Listener

Per ascoltare gli eventi, usa il addListener metodo 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`

Emesso durante il processo di download del bundle. Fornisce informazioni sull'avanzamento del download.

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

Dati dell'evento:

percent: number - Percentuale di progresso del download (0-100)
bundle: BundleInfo - Informazioni sul bundle in fase di download

`noNeedUpdate`

Eseguito quando il controllo 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 dell'evento:

bundle: BundleInfo - Informazioni sul bundle corrente

`updateAvailable`

Eseguito 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 dell'evento:

bundle: BundleInfo - Informazioni sul bundle di aggiornamento disponibile

`downloadComplete`

Viene attivato quando il download di un bundle è completato con successo.

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

Dati dell'evento:

bundle: BundleInfo - Informazioni sul bundle scaricato

`majorAvailable`

Viene attivato quando è disponibile un aggiornamento major, ma è bloccato dalle impostazioni di auto-update.

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

Dati dell'evento:

version: string - Il numero di versione del major update

`updateFailed`

Viene attivato quando l'installazione di un update fallisce 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 dell'evento:

bundle: BundleInfo - Informazioni sul bundle che non è stato possibile installare

`downloadFailed`

Viene attivato quando il download di un bundle fallisce.

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

Dati dell'evento:

version: string - La versione che non è stata scaricata

`appReloaded`

Viene attivato quando l'app viene ricaricata.

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

Dati dell'evento: Nessuna

`appReady`

Viene attivato quando l'app è pronta all'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 dell'evento:

bundle: BundleInfo - Informazioni sul bundle corrente
status: string - Lo stato 'ready'

Oggetto BundleInfo

Molti eventi includono un BundleInfo oggetto 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' - Bundle scaricato con successo
'error' - Errore nel download/installazione del bundle
'pending' - Bundle in attesa di essere impostato come prossimo
'downloading' - Download del bundle in corso

Esempio: flusso di aggiornamento completo

Ecco un esempio di come gestire l'intero flusso di aggiornamento tramite eventi:

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 practice

Chiamare sempre notifyAppReady(): Quando si usa l'auto-update, chiamare sempre questo metodo dopo l'inizializzazione dell'app per evitare il rollback.
Gestisci gli errori con eleganza: Implementare una gestione adeguata degli errori di download e update.
Fornire feedback all'utente: Usare l'evento download progress per mostrare agli utenti l'avanzamento dell'update.
Rimuovere i listener: Rimuovi gli event listener quando non sono più necessari per evitare memory leak.
Testare gli scenari di aggiornamento: Testa vari scenari di aggiornamento, inclusi fallimenti, rollback e major update.

Continua da Events

Se stai usando Eventi per pianificare il lavoro sui plugin nativi, collegalo a Usando @capgo/capacitor-updater per la funzionalità nativa in Usando @capgo/capacitor-updater, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.