Événements

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

Configuration de l'Event Listener

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

Fired during the bundle download process. Provides download progress information.

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

Event Data:

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

Remarque

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

noNeedUpdate

Déclenché 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);
});

Event Data:

• bundle: BundleInfo - Informations sur le bundle actuel

updateAvailable

Déclenché lorsqu'une nouvelle mise à jour est disponible au 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
});

Event Data:

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

downloadComplete

Déclenché lorsqu'un téléchargement de bundle 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
});

Event Data:

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

majorAvailable

Déclenché lorsqu'une mise à jour majeure est disponible mais bloquée par les paramètres d'auto-update.

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

Event Data:

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

Astuce

Major updates typically require user confirmation or app store updates. Use this event to notify users appropriately.

updateFailed

Déclenché lorsqu'une mise à jour n'a pas pu s'installer 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
});

Event Data:

• bundle: BundleInfo - Informations sur le bundle qui n'a pas pu être installé

downloadFailed

Déclenché lorsque le téléchargement d'un bundle a échoué.

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

Event Data:

• version: string - La version qui n'a pas pu être téléchargée

appReloaded

Déclenché lorsque l'application a été rechargée.

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

Event Data: Aucun

appReady

Déclenché lorsque l'application est prête à l'emploi 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);
});

Event Data:

• bundle: BundleInfo - Informations sur le bundle actuel
• status: string - le statut prêt

Attention

N'oubliez pas d'appeler notifyAppReady() dans le délai configuré (10 secondes par défaut) pour éviter un rollback automatique.

Objet BundleInfo

De nombreux événements incluent un BundleInfo objet 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 :

• 'success' - Bundle téléchargé avec succès
• 'error' - Échec du téléchargement/de l'installation du bundle
• 'pending' - Bundle is pending to be set as next
• 'downloading' - Le bundle est en cours de téléchargement

Exemple : flux de mise à jour complet

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

Attention

Ceci UpdateManager la classe n'inclut pas le CapacitorUpdater.notifyAppReady() appel requis pour le flux d'auto-update. Veuillez consulter le appeler notifyAppReady correctement la documentation 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
  }
}

Bonnes pratiques

1. Appelez toujours notifyAppReady(): Lors de l'utilisation de l'auto-update, appelez toujours cette méthode après l'initialisation de votre application pour éviter un rollback.

2. Gérer les échecs proprement: Implémentez une gestion d'erreurs appropriée pour les échecs de téléchargement et de mise à jour.

3. Fournir un retour utilisateur: Use the download progress event to show update progress to users.

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. Scénarios de test de mise à jour: Testez différents scénarios de mise à jour, incluant les échecs, les rollbacks et les mises à jour majeures.

Continuer depuis Events

Si vous utilisez Événements pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-updater pour la capacité native dans « Utiliser @capgo/capacitor-updater », Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.