アップデートの動作

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

Capgo アプリのアップデートをリリースするとき、ユーザーにはできるだけ早くそのアップデートを受け取ってほしいと考えるでしょう。しかし、ダウンロードを待たせたり、セッションの途中でアプリを再起動させたりして、ユーザー体験を損ないたくはないはずです。

Capgo の更新動作は、迅速な更新配信とユーザーへの影響最小化のバランスを取るよう設計されています。

デフォルトのアップデートフロー

デフォルトでは、Capgo はアプリの更新を以下のように処理します。

アプリがフォアグラウンドに移行すると、Capgo プラグインが新しい更新の有無を確認します。アプリが開いている間も、以下の設定で制御される繰り返しタイマーで再確認を行います。 periodCheckDelay （デフォルトは10分間隔）。
更新が見つかった場合、ユーザーが現在のバージョンのアプリを使い続けながら、バックグラウンドでダウンロードされます。
ダウンロードが完了すると、Capgo はユーザーがアプリをバックグラウンドに移すのを待ちます。
ユーザーが次にアプリをフォアグラウンドに戻したとき、更新されたバージョンが実行されます。

このフローにより、更新プロンプトで中断されたり、ダウンロードを待つ必要がなかったりしながら、ユーザーは常にアプリの最新バージョンを使用できます。

このアプローチを採用する理由

バックグラウンド移行時や kill 時にアップデートを適用することには、ユーザー体験上の大きなメリットがいくつかあります：

セッションの途中でアップデートのプロンプトが表示されたり、ダウンロードを待たされたりすることがありません。
セッションの合間にシームレスにアップデートが適用されるため、アプリを起動するたびに常に最新の状態を利用できます。
アクティブなユーザーの操作を妨げる心配をせずに、頻繁にアップデートを配信できます。

主なデメリットは、ユーザーがアプリをバックグラウンドに送ってすぐ復帰すると、その間にアップデートが適用されて未保存の状態が失われる可能性があることです。

これを軽減するために、以下の方法を推奨します：

state を頻繁に保存し、アプリ復帰時にスムーズに復元すること。
アプリの state の大部分を変更するような頻繁すぎるアップデートを避けること。
機微なフローでは、更新の動作をカスタマイズすることを検討してください（下記参照）。

アップデート適用タイミングのカスタマイズ

場合によっては、更新が適用されるタイミングをより厳密に制御したい場合があります。例えば、ユーザーが進行中のフローを完了するまで更新を待たせたり、サーバー側の変更とアプリの更新を同期させたりすることがあります。

Capgo は、 setDelay 更新がインストールされる前に満たされるべき条件を指定できる関数：

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

この例では、2023年6月1日以降かつ、アプリがバックグラウンドで少なくとも60秒間停止した後に、更新のインストールを遅延させます。

利用可能な遅延条件は以下の通りです：

date：特定の日付/時刻を過ぎるまで待ってから、更新を適用します。
background：アプリがバックグラウンドになってから更新を適用するまで、最低限の待機時間を設けます。
nativeVersion：更新を適用する前に、最低バージョンのネイティブバイナリがインストールされるまで待機します。
kill：次のアプリ終了イベントまで待ってから、更新を適用します。

これらの条件を組み合わせて、更新がインストールされるタイミングを正確に制御できます。

アップデートを即座に適用

クリティカルな更新や、状態が非常にシンプルなアプリの場合、バックグラウンドイベントや終了イベントを待たずに、ダウンロードが完了したらすぐに更新を適用したい場合があります。Capgo は、 autoUpdate お使いの Capacitor 設定のポリシーでこれをサポートしています。

"atInstall", "onLaunch"や "always" ユーザーが待っている間に更新を適用します。使用差分アップデートこれにより、変更されたファイルのみがダウンロードされます。フルZIPのアップロードはユーザー体験を損なうためです。

これらのモードでは、以下も必要です： @capacitor/splash-screen と autoSplashscreen: true を使用して SplashScreen.launchAutoHide: false。splashプラグインがない場合、アップデート適用中に画面がちらついたり、古いUIが表示されたりすることがあります。

次の場合: autoUpdate が次のように設定されています： "atInstall", "onLaunch"、または "always" に capacitor.config、お使いの CLI がそれを検出します。非対話型環境では Delta updates を自動送信し、対話型環境ではアップロード前に確認を求めます。従来の directUpdate 設定も引き続き検出されます。フルバンドルを強制的にアップロードするには --no-delta を使用してください。

npx @capgo/cli@latest bundle upload --delta

autoUpdate は、あなたの capacitor.config.ts ファイルに設定されており、JavaScript の code ではありません。以下の値をサポートしています:

false または 'off'：自動更新チェックを無効にする
true または 'atBackground' (デフォルト): フォアグラウンドチェックのたびに自動で確認・ダウンロードし、アプリがバックグラウンドに移行した際に更新を適用します
'atInstall': 新規インストールまたはネイティブアプリのストア更新直後のみ即時適用します。それ以外の場合は "atBackground" の動作を使用します
'onLaunch': アプリがキルされた状態からフォアグラウンドに復帰したとき（コールドスタート）にのみ即時適用します。最初のチェック以降はフォールバックします "atBackground" の動作を使用します
'always': フォアグラウンド移行のたびにチェックを行い、アップデートがあれば即時適用します
'onlyDownload': 自動的にチェックとダウンロードを行い、emit し updateAvailable、次のbundleの設定やアップデートの自動適用は行いません

Live UpdatesなしでNative Buildをテストする

詳細は Live UpdatesなしでNative Buildをテストネイティブバージョン、チャネルポリシー、および CI 設定のセーフガードについて。

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required for instant apply with autoSplashscreen
    },
  },
};

export default config;

を使用すると、 autoUpdate: 'always', Capgo は、フォアグラウンドへの移行のたびにチェックを行い、そのチェック中にダウンロードが完了すると、ユーザーがアプリを使用中でも即座にアップデートを適用します。また、 periodCheckDelay によって制御される定期的なチェックでも、アプリが開いている間に同じ即時適用動作をトリガーできます。

注意点として、 autoUpdate はネイティブの設定であるため、instant apply モードを使用する場合は、JavaScript の code で追加の処理が必要になります。

適用せずに自動ダウンロード

Capgo が更新のチェックとダウンロードを自動的に行うが、適用は決して自動的に行わないようにするには、以下を使用します autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

このモードでは、プラグインが updateAvailable をバンドルのダウンロード後に発火します。アプリ側で呼び出しタイミングを判断できます。 CapacitorUpdater.set() または独自の更新プロンプトを表示します。

Splashscreenの自動制御

即時適用モード ("atInstall", "onLaunch", "always") が必要です autoSplashscreen と @capacitor/splash-screen (バージョン 7.6.0 以降で利用可能)。プラグインをインストールした後、Capgo が非表示にするまでスプラッシュを表示し続けます：

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

次の場合: autoSplashscreen が有効な場合：

プラグインは、アップデートが適用されると自動的にスプラッシュスクリーンを非表示にします
アップデートが不要な場合、プラグインが自動的にスプラッシュスクリーンを非表示にします
手動で appReady イベントをリッスンしたり、呼び出したりする必要はありません SplashScreen.hide()

Splashscreen非表示後の追加処理

保持 autoSplashscreen: true. アップデートの準備ができた後に追加のロジックが必要な場合は、次をリッスンしてください： appReady も同様です。スプラッシュプラグインをスキップしたり、 autoSplashscreen これには次を使用します：

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

この appReady このイベントは、アプリの初期化と保留中のアップデートの適用が完了すると一度発火します。

設定 keepUrlPathAfterReload まで true instant apply モードを使用する場合です。これにより、アップデートでアプリが再読み込みされても現在のURLパスが保持されます。

instant apply モードの使用は、重大なバグ修正やセキュリティパッチの配信に役立ちますが、いくつかのトレードオフがあります：

次の条件で、アップデート適用時に一瞬のちらつきやローディング状態が表示されることがあります： @capacitor/splash-screen が欠落しているか、 autoSplashscreen が有効になっていません。
アップデートでアプリの状態や UI が変更されると、セッションの途中でユーザーに混乱を招く変化が起きる可能性があります。
次の場合、アプリ内でのユーザーの現在位置が失われる可能性があります： keepUrlPathAfterReload が設定されておらず、ユーザーが混乱する可能性があります。
スムーズな遷移を実現するには、状態の保存と復元を慎重に処理する必要があります。

instant apply を有効にする場合は、以下を推奨します：

でアップロード npx @capgo/cli@latest bundle upload --delta ダウンロードによるユーザー体験の低下を防ぎます。
インストール @capacitor/splash-screen および設定 autoSplashscreen: true を使用して launchAutoHide: false.
設定 keepUrlPathAfterReload まで true アプリ内でのユーザーの位置を保持するため。
必要に応じてアプリの状態を保存・復元し、ユーザーの進行状況が失われないようにします。
唐突な画面遷移や状態の消失、ユーザーが戸惑うような位置の変化が起きないよう、アプリのアップデート挙動を徹底的にテストしてください。

ほとんどの場合、デフォルトのアップデート挙動が、迅速な配信と中断の最小化のバランスにおいて最適です。しかし、特定のニーズを持つアプリでは、Capgo によりアップデートを適用するタイミングと方法をカスタマイズできます。

Update Behavior の続きを読む

使用している場合 アップデートの動作 live update の配信を計画するには、以下と連携させます： Capgo Live Update Capgo Live Updates のプロダクトワークフロー向けに、概要実装の詳細は Overview を機能実装の詳細は Features をアップデートの種類 Update Types の実装詳細については、スタートガイド実装の詳細については、Getting Started を参照してください。