Événements

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

Paramètres de l'écouteur d'événements

Pour écouter les événements, utilisez la addListener méthode sur l' CapacitorUpdater objet :

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

Émis pendant le processus de téléchargement du bundle. fournit des informations sur le progrès de téléchargement.

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

Données de l'événement :

• percent: nombre - Pourcentage de progrès de téléchargement (0-100)
• bundle: BundleInfo - Informations sur le bundle téléchargé

Note

Cet événement est émis plusieurs fois pendant le téléchargement pour signaler le progrès.

noNeedUpdate

Émis lorsqu'une vérification de mise à jour détermine qu'une mise à jour n'est pas nécessaire.

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

Données de l'événement :

• bundle: BundleInfo - Informations sur le bundle actuel

updateAvailable

Émis lorsqu'une nouvelle mise à jour est disponible pour le 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 de l'événement :

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

downloadComplete

Émis lorsqu'un téléchargement de bundle a été effectué 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 de l'événement :

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

majorAvailable

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

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

Données de l'événement :

• version: chaîne - Le numéro de version de la mise à jour majeure

Conseil

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

updateFailed

Déclenché lorsque l'installation d'une mise à jour a échoué à la prochaine 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 de l'événement :

• bundle: BundleInfo - Informations sur le bundle qui n'a pas pu s'installer

downloadFailed

Déclenché 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 de l'événement :

• version: chaîne - La version qui n'a pas pu se télécharger

appReloaded

Déclenché lorsqu'une application a été rechargée.

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

Données de l'é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 de l'événement :

• bundle: BundleInfo - Informations sur le bundle actuel
• status: chaîne - L'état prêt

Attention

N'oubliez pas d'appeler notifyAppReady() dans le délai configuré (par défaut 10 secondes) pour empêcher le 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' - Le bundle a été téléchargé avec succès
• 'error' - Le téléchargement/ installation du bundle a échoué
• 'pending' - Le bundle est en attente d'être défini comme le prochain
• 'downloading' - Le bundle est actuellement 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

Ce UpdateManager classe ne comprend pas l'appel requis pour le flux de mise à jour automatique. Veuillez consulter les CapacitorUpdater.notifyAppReady() docs pour plus d'informations sur la mise en place correcte de l'appel notifyAppReady. Copier dans le presse-papier Meilleures Pratiques

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

Toujours appeler

1. Lors de l'utilisation de la mise à jour automatique, appelez toujours cette méthode après l'initialisation de votre application pour éviter le rollback. notifyAppReady()Lors de l'utilisation de la mise à jour automatique, appelez toujours cette méthode après l'initialisation de votre application pour éviter le rollback.

2. Gérer les échecs avec élégance: Mettre en œuvre un traitement d'erreurs approprié pour les échecs de téléchargement et de mise à jour.

3. Fournir des retours d'information à l'utilisateur: Utiliser l'événement de progression de téléchargement pour afficher la progression de mise à jour aux utilisateurs.

4. Nettoyer les écouteurs: Supprimer les écouteurs d'événements lorsque ceux-ci ne sont plus nécessaires pour éviter les fuites de mémoire.

5. Tester les scénarios de mise à jour: Tester divers scénarios de mise à jour, notamment les échecs, les retours en arrière et les mises à jour majeures.

Continuez de la section Événements

Si vous utilisez Événements planifier le travail de plugin natif, le connecter à Utiliser @capgo/capacitor-mises à jour pour la capacité native dans Utiliser @capgo/capacitor-mises à jour, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, Plugins Capacitor par Capgo pour le détail d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou Mettre à jour des Plugins pour le détail d'implémentation dans Ajouter ou Mettre à jour des Plugins, et Alternatives de Plugin d'Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugin d'Entreprise Ionic.