Events

El complemento Capacitor Updater proporciona varios eventos que puede escuchar para monitorear el proceso de actualización y responder a diferentes estados.

Configuración del detector de eventos

Para escuchar eventos, use el método addListener en el objeto 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();

Eventos disponibles

download

Activado durante el proceso de descarga del paquete. Proporciona información sobre el progreso de la descarga.

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

Datos del evento:

• percent: número - Porcentaje de progreso de descarga (0-100)
• bundle: BundleInfo - Información sobre el paquete que se está descargando

Nota

Este evento se activa varias veces durante la descarga para informar el progreso.

noNeedUpdate

Se activa cuando una búsqueda de actualizaciones determina que no se necesita ninguna actualización.

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

Datos del evento:

• bundle: BundleInfo - Información sobre el paquete actual

updateAvailable

Se activa cuando hay una nueva actualización disponible para descargar.

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

Datos del evento:

• bundle: BundleInfo - Información sobre el paquete de actualización disponible

downloadComplete

Se activa cuando la descarga de un paquete se completa correctamente.

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

Datos del evento:

• bundle: BundleInfo - Información sobre el paquete descargado

majorAvailable

Se activa cuando hay una actualización importante disponible pero está bloqueada por la configuración de actualización automática.

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

Datos del evento:

• version: cadena - El número de versión de la actualización principal

Consejo

Las actualizaciones importantes normalmente requieren la confirmación del usuario o actualizaciones de la tienda de aplicaciones. Utilice este evento para notificar a los usuarios de forma adecuada.

updateFailed

Se activa cuando no se pudo instalar una actualización en el siguiente inicio de la aplicación.

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

Datos del evento:

• bundle: BundleInfo - Información sobre el paquete que no se pudo instalar

downloadFailed

Se activa cuando falla la descarga de un paquete.

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

Datos del evento:

• version: cadena - La versión que no se pudo descargar

appReloaded

Se activa cuando se recarga la aplicación.

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

Datos del evento: Ninguno

appReady

Se activa cuando la aplicación está lista para usarse después de una actualización.

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

Datos del evento:

• bundle: BundleInfo - Información sobre el paquete actual
• status: cadena - El estado listo

Precaución

Recuerde llamar a notifyAppReady() dentro del tiempo de espera configurado (predeterminado 10 segundos) para evitar la reversión automática.

Objeto BundleInfo

Muchos eventos incluyen un objeto BundleInfo con las siguientes propiedades:

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
}

Donde BundleStatus puede ser:

• 'éxito' - Paquete descargado exitosamente
• 'error' - Falló la descarga/instalación del paquete
• 'pendiente': el paquete está pendiente de establecerse como el siguiente
• 'descargando' - El paquete se está descargando actualmente

Ejemplo: Flujo de actualización completo

A continuación se muestra un ejemplo de manejo del flujo de actualización completo con eventos:

Precaución

Esta clase UpdateManager no incluye la llamada CapacitorUpdater.notifyAppReady() requerida para el flujo de actualización automática. Consulte los documentos realizar la llamada notifyAppReady correctamente para obtener más información.

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

Mejores prácticas1. Llame siempre a notifyAppReady(): cuando utilice la actualización automática, llame siempre a este método después de que su aplicación se inicialice para evitar la reversión.

2. Maneje las fallas con elegancia: implemente un manejo adecuado de errores para las fallas de descarga y actualización.

3. Proporcionar comentarios de los usuarios: utilice el evento de progreso de descarga para mostrar el progreso de la actualización a los usuarios.

4. Limpiar oyentes: elimine los oyentes de eventos cuando ya no sean necesarios para evitar pérdidas de memoria.

5. Escenarios de actualización de prueba: Pruebe varios escenarios de actualización, incluidos fallos, reversiones y actualizaciones importantes.