Events

The Capacitor Updater plugin provides several events you can listen to for monitoring the Mise à jour process and responding to different states.

Event Listener Configuration

To listen to events, use the addListener method on the CapacitorUpdater object:

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

Disponible Events

download

Fired during the Bundle Télécharger process. Provides Télécharger progress Information.

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

Event Data:

• percent: number - Download progress percentage (0-100)
• bundle: BundleInfo - Information about the bundle being downloaded

Note

This event fires multiple times during Télécharger to Signaler progress.

noNeedUpdate

Fired when a Vérifier for Mises à jour determines that no Mise à jour is needed.

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

Event Data:

• bundle: BundleInfo - Information about the current bundle

updateAvailable

Fired when a Nouveau Mise à jour is Disponible for Télécharger.

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

Event Data:

• bundle: BundleInfo - Information about the available update bundle

downloadComplete

Fired when a Bundle Télécharger has completed successfully.

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

Event Data:

• bundle: BundleInfo - Information about the downloaded bundle

majorAvailable

Fired when a major Mise à jour is Disponible but blocked by auto-Mise à jour Paramètres.

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

Event Data:

• version: string - The version number of the major update

Astuce

Major Mises à jour typically require Utilisateur confirmation or Application Store Mises à jour. Use this event to notify Utilisateurs appropriately.

updateFailed

Fired when an Mise à jour has Échoué to Installer at the Suivant Application Démarrer.

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

Event Data:

• bundle: BundleInfo - Information about the bundle that failed to install

downloadFailed

Fired when a Bundle Télécharger has Échoué.

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

Event Data:

• version: string - The version that failed to download

appReloaded

Fired when the Application has been reloaded.

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

Event Data: None

appReady

Fired when the Application is ready to use after an Mise à jour.

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

Event Data:

• bundle: BundleInfo - Information about the current bundle
• status: string - The ready status

Attention

Remember to call notifyAppReady() within the configured timeout (default 10 seconds) to prevent automatic rollback.

BundleInfo Object

Many events include a BundleInfo object with the following properties:

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
}

Where BundleStatus can be:

• 'success' - Bundle downloaded successfully
• 'error' - Bundle download/installation failed
• 'pending' - Bundle is pending to be set as next
• 'downloading' - Bundle is currently downloading

Exemple: Terminé Mise à jour Flow

Here’s an Exemple of handling the Terminé Mise à jour flow with events:

Attention

This UpdateManager class does not include the CapacitorUpdater.notifyAppReady() call required for auto-update flow. Please see the [placing notifyAppReady call correctly](/docs/plugins/updater/auto-Mise à jour#placing-notifyappready-call-correctly) docs for more Information.

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 Practices

1. Always call notifyAppReady(): When using auto-update, always call this method after your app initializes to prevent rollback.

2. Handle failures gracefully: Implement proper Erreur handling for Télécharger and Mise à jour failures.

3. Provide Utilisateur Retour: Use the Télécharger progress event to show Mise à jour progress to Utilisateurs.

4. Clean up listeners: Retirer event listeners when they’re no longer needed to prevent memory leaks.

5. Test Mise à jour scenarios: Test various Mise à jour scenarios including failures, Restaurations, and major Mises à jour.