事件

Capacitor Updater 插件提供了多个事件，你可以监听这些事件来监控更新过程并响应不同状态。

事件监听器设置

若要监听事件，请在 addListener 对象上使用 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();

可用事件

download

在 bundle 下载过程中触发。提供下载进度信息。

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

事件数据：

• percent: number - 下载进度百分比 (0-100)
• bundle: BundleInfo - 正在下载的 bundle 信息

注意

此事件在下载过程中会多次触发，用于报告进度。

noNeedUpdate

当检查更新后确定无需更新时触发。

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

事件数据：

• bundle: BundleInfo - 当前 bundle 的信息

updateAvailable

当有新的更新可供下载时触发。

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

事件数据：

• bundle: BundleInfo - 关于可用更新 bundle 的信息

downloadComplete

当 bundle 下载成功完成后触发。

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

事件数据：

• bundle: BundleInfo - 关于已下载 bundle 的信息

majorAvailable

当有 major update 可用但被 auto-update 设置拦截时触发。

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

事件数据：

• version: string - 大版本更新的版本号

提示

大版本更新通常需要用户确认或通过 App Store 更新。请使用此事件向用户发出适当通知。

updateFailed

当更新无法在下次应用启动时安装时触发。

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

事件数据：

• bundle: BundleInfo - 安装失败的 bundle 相关信息

downloadFailed

当 bundle 下载失败时触发。

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

事件数据：

• version: string - 下载失败的版本

appReloaded

应用重新加载后触发。

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

事件数据： 无

appReady

更新后应用准备就绪时触发。

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

事件数据：

• bundle: BundleInfo - 当前 bundle 的信息
• status: string - 就绪状态

注意

请记得调用 notifyAppReady() 需在配置的超时时间内（默认 10 秒）完成，以防止自动回滚。

BundleInfo 对象

许多事件包含一个 BundleInfo 具有以下属性的对象：

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
}

其中 BundleStatus 可以是：

• 'success' - Bundle 下载成功
• 'error' - Bundle 下载/安装失败
• 'pending' - Bundle 等待设为下一个版本
• 'downloading' - Bundle 正在下载中

示例：完整的更新流程

以下是使用事件处理完整更新流程的示例：

注意

此项 UpdateManager 类中未包含 CapacitorUpdater.notifyAppReady() 自动更新流程所需的调用。 请参阅 正确调用 notifyAppReady 查阅文档了解更多信息。

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

最佳实践

1. 务必调用 notifyAppReady(): 使用 auto-update 时，请务必在应用初始化完成后调用此方法，以防止回滚。

2. 优雅地处理失败情况: 针对 download 和 update 失败实现完善的错误处理机制。

3. 提供用户反馈: 利用 download progress 事件向用户展示更新进度。

4. 清理监听器: 在不再需要时移除事件监听器，以防止内存泄漏。

5. 测试更新场景: 测试各种更新场景，包括失败、回滚和大版本更新。

从 Events 继续

如果你正在使用 事件 要规划原生插件工作，请将其与 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。