Events

Le plugin Capacitor Updater fournit plusieurs événements que vous pouvez écouter pour surveiller le processus de mise à jour et répondre aux différents états.

Configuration de l’écouteur d’événement

Pour écouter les événements, utilisez la méthode addListener sur l’objet 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();

Événements disponibles

download

Lancé pendant le processus de téléchargement du bundle. Fournit des informations sur la progression du téléchargement.

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

Données d’événement :

• percent : numéro - Pourcentage de progression du téléchargement (0-100)
• bundle : BundleInfo - Informations sur le bundle en cours de téléchargement

Note

Cet événement se déclenche plusieurs fois pendant le téléchargement pour signaler la progression.

noNeedUpdate

Lancé lorsqu’une vérification des mises à jour détermine qu’aucune mise à jour n’est nécessaire.

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

Données d’événement :

• bundle : BundleInfo - Informations sur le forfait actuel

updateAvailable

Lancé lorsqu’une nouvelle mise à jour est disponible en téléchargement.

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

Données d’événement :

• bundle : BundleInfo - Informations sur le bundle de mise à jour disponible

downloadComplete

Lancé lorsqu’un téléchargement de bundle s’est terminé avec succès.

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

Données d’événement :

• bundle : BundleInfo - Informations sur le bundle téléchargé

majorAvailable

Lancé lorsqu’une mise à jour majeure est disponible mais bloqué par les paramètres de mise à jour automatique.

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

Données d’événement :

• version : string - Le numéro de version de la mise à jour majeure

Astuce

Les mises à jour majeures nécessitent généralement une confirmation de l’utilisateur ou des mises à jour de l’App Store. Utilisez cet événement pour informer les utilisateurs de manière appropriée.

updateFailed

Déclenché lorsqu’une mise à jour n’a pas pu être installée au prochain démarrage de l’application.

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

Données d’événement :

• bundle : BundleInfo - Informations sur le bundle dont l’installation a échoué

downloadFailed

Lancé lorsqu’un téléchargement de bundle a échoué.

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

Données d’événement :

• version : chaîne - La version dont le téléchargement a échoué

appReloaded

Lancé lorsque l’application a été rechargée.

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

Données d’événement : Aucune

appReady

Déclenché lorsque l’application est prête à être utilisée après une mise à jour.

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

Données d’événement :

• bundle : BundleInfo - Informations sur le forfait actuel
• status : string - L’état prêt

Attention

N’oubliez pas d’appeler notifyAppReady() dans le délai d’expiration configuré (10 secondes par défaut) pour empêcher la restauration automatique.

Objet BundleInfo

De nombreux événements incluent un objet BundleInfo avec les propriétés suivantes :

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
}

Où BundleStatus peut être :

• “succès’` - Bundle téléchargé avec succès
• “erreur’` - Le téléchargement/l’installation du bundle a échoué
• “en attente’` - Le bundle est en attente d’être défini comme suivant
• “téléchargement’` - Le bundle est en cours de téléchargement

Exemple : terminer le flux de mise à jour

Voici un exemple de gestion du flux de mise à jour complet avec des événements :

Attention

Cette classe UpdateManager n’inclut pas l’appel CapacitorUpdater.notifyAppReady() requis pour le flux de mise à jour automatique. Veuillez consulter la documentation [placer correctement l’appel notifyAppReady] (/docs/plugins/updater/auto-update#placing-notifyappready-call-correctly) pour plus d’informations.

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

## meilleures pratiques1. Toujours appeler notifyAppReady() : lorsque vous utilisez la mise à jour automatique, appelez toujours cette méthode après l’initialisation de votre application pour empêcher la restauration.

2. Gérez les échecs avec élégance : implémentez une gestion appropriée des erreurs pour les échecs de téléchargement et de mise à jour.

3. Fournir des commentaires aux utilisateurs : utilisez l’événement de progression du téléchargement pour afficher la progression de la mise à jour aux utilisateurs.

4. Nettoyer les écouteurs : supprimez les écouteurs d’événements lorsqu’ils ne sont plus nécessaires pour éviter les fuites de mémoire.

5. Testez les scénarios de mise à jour : testez divers scénarios de mise à jour, notamment les échecs, les restaurations et les mises à jour majeures.