Eventos

El plugin Capacitor Updater ofrece varios eventos que puedes escuchar para monitorear el proceso de actualización y responder a diferentes estados.

Configuración del Event Listener

Para escuchar eventos, usa 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

Se dispara durante la descarga del bundle. Proporciona información del progreso de descarga.

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

Datos del evento:

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

Nota

Este evento se dispara varias veces durante la descarga para reportar el progreso.

noNeedUpdate

Se dispara cuando la comprobación de actualizaciones determina que no es necesaria ninguna.

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 bundle actual

updateAvailable

Se dispara 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 bundle de actualización disponible

downloadComplete

Se dispara cuando la descarga de un bundle finaliza con éxito.

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 bundle descargado

majorAvailable

Fired when a major update is available but blocked by auto-update settings.

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

Datos del evento:

• version: string - El número de versión de la actualización mayor

Consejo

Las actualizaciones mayores suelen requerir confirmación del usuario o actualizaciones en la app store. Usa este evento para notificar a los usuarios adecuadamente.

updateFailed

Se dispara cuando una actualización no logra instalarse en el siguiente inicio de la app.

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 bundle que falló al instalarse

downloadFailed

Se dispara cuando falla la descarga de un bundle.

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

Datos del evento:

• version: string - La versión que falló al descargarse

appReloaded

Se dispara cuando la app se ha recargado.

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

Datos del evento: Ninguno

appReady

Se dispara cuando la app está lista para usarse tras 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 bundle actual
• status: string - El estado de listo

Precaución

Recuerda llamar a notifyAppReady() dentro del timeout configurado (10 segundos por defecto) para evitar el rollback automático.

Objeto BundleInfo

Muchos eventos incluyen un BundleInfo objeto 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:

• 'success' - Bundle descargado con éxito
• 'error' - Error al descargar/instalar el bundle
• 'pending' - Bundle is pending to be set as next
• 'downloading' - El bundle se está descargando

Ejemplo: flujo de actualización completo

Aquí tienes un ejemplo de cómo manejar el flujo de actualización completo con eventos:

Precaución

Esto UpdateManager la clase no incluye el CapacitorUpdater.notifyAppReady() llamada necesaria para el flujo de auto-update. Consulta el colocar la llamada notifyAppReady correctamente la documentación para 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
  }
}

Buenas prácticas

1. Llamar siempre a notifyAppReady(): Al usar auto-update, llama siempre a este método tras inicializar tu app para evitar un rollback.

2. Gestionar fallos con elegancia: Implementa un manejo de errores adecuado para fallos en el download y la update.

3. Dar feedback al usuario: Usa el evento de progreso de download para mostrar el avance de la update a los usuarios.

4. Limpiar los listeners: Elimina los event listeners cuando ya no sean necesarios para evitar fugas de memoria.

5. Probar escenarios de actualización: Prueba varios escenarios de actualización, incluyendo fallos, rollbacks y actualizaciones mayores.

Continuar desde Events

Si estás usando Eventos para planificar el trabajo con plugins nativos, conéctalo con Al usar @capgo/capacitor-updater para la funcionalidad nativa al usar @capgo/capacitor-updater, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.