イベント

Capacitor Updater pluginは、アップデートプロセスの監視や各ステータスへの対応ができるよう、複数のイベントを提供しています。

イベントリスナーの設定

イベントをリッスンするには、 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

メジャーアップデートが利用可能ですが、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 class には、 CapacitorUpdater.notifyAppReady() 自動アップデートフローに必要な call が含まれていません。 次を参照してください： 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. 失敗を適切に処理する: ダウンロードやアップデートの失敗に対して、適切なエラーハンドリングを実装してください。

3. ユーザーにフィードバックを表示する: download progress イベントを使用して、アップデートの進捗状況をユーザーに表示してください。

4. リスナーのクリーンアップ: メモリリークを防ぐため、不要になったイベントリスナーは削除してください。

5. アップデートシナリオをテスト: 失敗、ロールバック、メジャーアップデートなど、さまざまなアップデートシナリオをテストします。

Events の次のステップ

使用している場合 イベント ネイティブプラグインの作業を計画するには、次と連携してください： @capgo/capacitor-updater を使用する 「@capgo/capacitor-updater を使用する」のネイティブ機能については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 プラグインの追加または更新 プラグインの追加または更新における実装詳細については、および Ionic Enterprise プラグインの代替案 Ionic Enterprise プラグインの代替案におけるプロダクトワークフローについては。