Eventos

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

Configuración del escuchador de eventos

Para escuchar eventos, utiliza el método en el objeto: addListener Copiar al portapapeles CapacitorUpdater Eventos disponibles

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

Para escuchar eventos, utiliza el método en el objeto:

download

Se dispara durante el proceso de descarga del paquete. Proporciona información de progreso de 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 dispara varias veces durante la descarga para informar el progreso.

noNeedUpdate

Se dispara cuando una comprobación de actualizaciones determina que no hay actualización necesaria.

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

Datos del evento:

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

updateAvailable

Se dispara cuando está disponible una nueva actualización para su descarga.

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: Información sobre el paquete de actualización disponible - Información sobre el paquete de actualización disponible

downloadComplete

Se dispara cuando se ha completado con éxito la descarga de un paquete.

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: Información de Bundle - Información sobre el paquete descargado

majorAvailable

Se dispara cuando hay una actualización importante disponible pero bloqueada por los ajustes 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: string - El número de versión de la actualización importante

Consejo

Las actualizaciones importantes suelen requerir confirmación del usuario o actualizaciones de tienda. Utilice este evento para informar a los usuarios de manera adecuada.

updateFailed

Se dispara cuando una actualización ha fallado al instalarse en la próxima apertura 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: Información del paquete que no se instaló correctamente

downloadFailed

Se dispara cuando se falla el descarga de un paquete.

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 no se pudo descargar

appReloaded

Se dispara cuando se recarga la aplicación.

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

Datos del evento: None

appReady

Se dispara cuando la aplicación está lista para su uso 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: Información del paquete actual - Información sobre el paquete actual
• status: string - El estado de preparación

Advertencia

Recuerde llamar notifyAppReady() dentro del tiempo de espera configurado (por defecto 10 segundos) 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' - Descarga de paquete exitosa
• 'error' - Fallo en la descarga o instalación del paquete
• 'pending' - Paquete pendiente de configurarse como el siguiente
• 'downloading' - Paquete actualmente descargándose

Ejemplo: Flujo de actualización completo

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

Precaución

Esta UpdateManager clase no incluye la CapacitorUpdater.notifyAppReady() llamada requerida para el flujo de actualización automática. Consulte los docs para obtener más información sobre la colocación de la llamada notifyAppReady correctamente. Copiar a portapapeles

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

Sección titulada “Prácticas recomendadas”

1. : Cuando se utiliza la actualización automática, siempre llama a este método después de que tu aplicación se inicie para evitar el rechazo. notifyAppReady()Copia al portapapeles

2. Gestione las fallas con amabilidad: Implemente un manejo de errores adecuado para fallas de descarga y actualización.

3. Proporcione retroalimentación al usuario: Utilice el evento de progreso de descarga para mostrar el progreso de la actualización a los usuarios.

4. Limpie los oyentes: Elimine los oyentes de eventos cuando ya no sean necesarios para evitar fugas de memoria.

5. Pruebe escenarios de actualización: Pruebe varios escenarios de actualización, incluyendo fallas, retrocesos y actualizaciones importantes.

Sigue adelante desde Eventos

Si está utilizando Eventos para planificar el trabajo de plugin nativo, conectarlo con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Directorio de Plugin Capgo para el flujo de trabajo del producto en Directorio de Plugin Capgo, Plugins de Capacitor por Capgo para el detalle de implementación en Plugins de Capacitor por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise.