更新の適用方法

このプラグインのインストール手順と全体のマークダウンガイドを含むセットアップコマンドをコピーする。

あなたの Capgo アプリにアップデートをリリースしたとき、ユーザーがそのアップデートを受け取るのをできるだけ早くしたいと思うでしょう。ただし、ダウンロード待ちやセッション中のアプリを再起動させることなく、ユーザーの体験を最小限に抑えたいと思うでしょう。

Capgo のアップデートの動作は、ユーザーにアップデートをできるだけ早く提供し、ユーザーの体験を最小限に抑えるバランスを取るように設計されています。

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

Capgoはデフォルトで、以下の方法でアプリの更新を処理します:

アプリ起動時に、Capgo プラグインは、最新の更新が利用可能かどうかを確認します。
更新が見つかった場合、バックグラウンドでダウンロードされます。ユーザーは現在のアプリのバージョンを使用し続けます。
ダウンロードが完了したら、Capgoはユーザーがアプリをバックグラウンドに送ったり、完全に終了したりするのを待ちます。
ユーザーがアプリを再起動すると、最新のバージョンを実行します。

このフローは、ユーザーに更新のポップアップやダウンロードの待機を強制することなく、常に最新のアプリのバージョンを実行することを保証します。

なぜこのアプローチを採用するのか?

バックグラウンドまたは終了イベントでアップデートを適用することには、ユーザー体験にいくつかの重要な利点があります:

ユーザーはアップデートのプロンプトに打ち勝たず、セッションの途中でダウンロードを待たずに、正常にアプリケーションを使用できます。
アップデートはセッションの間隔で自動的に適用されるため、アプリケーションを起動するときの体験は常に新鮮です。
頻繁にアップデートを配信することができますが、有効なユーザーに影響を与える心配はありません。

主な欠点は、ユーザーがアプリケーションをバックグラウンドにし、すぐにアプリケーションを再開すると、更新が適用された間のアクションで保存されていない状態が失われる可能性があることです。

このリスクを軽減するために、以下の推奨事項があります。

頻繁に保存し、再開したときに優雅に復元するように状態を保存する。
大きなアプリケーション状態を変更するアップデートを頻繁に配信しない。
重要なフローをカスタマイズする (以下を参照)。

アップデートの適用時期をカスタマイズする

いくつかの場合、アップデートの適用時期をより制御できるようにしたいと思うかもしれません。たとえば、ユーザーが進行中のフローを完了するまでアップデートを適用したい、またはサーバーサイドの変更とアプリケーションアップデートを調整したいなどです。

Capgoは提供する setDelay functionが条件を指定してアップデートをインストールする前に満たす必要があることを指定できる:

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は、Capgoの設定ファイルの autoUpdate policy in your Capacitor config.

即時適用モードを使用する場合、 強く推奨 Delta (マニフェスト) アップデートを有効にする Delta (マニフェスト) アップデートを有効にするダウンロード時間を最小限に抑え、ユーザー体験を向上させるために。デルタ(マニフェスト)更新では、変更されたファイルのみをダウンロードするため、全体のバンドルではなく、特に更新が即時適用される場合に重要です。

インスタント適用モードの重要性

迅速な更新: ダウンロードサイズが小さくなるため、更新が早く完了し、ロード画面が表示される時間が短縮されます。
改善されたモバイル体験: セルラーネットワークや低速な接続環境のユーザーは、長い待ち時間に遭遇しません。
帯域幅の低減: 変更されたファイルのみがダウンロードされるため、データの消費量が両方のユーザーにとって節約されます。

設定 autoUpdate が "atInstall", "onLaunch"、 "always" または capacitor.config、CLIはそれを検出します。非対話型環境では、Delta (マニフェスト)更新を自動的に送信し、対話型環境では、アップロードする前に確認を求めます。Legacy directUpdate configはまだ検出されます。 --no-delta を使用して、完全なバンドルアップロードを強制します。

Delta (マニフェスト)更新を有効にするには、単に --delta フラグを使用して、バンドルをアップロードしてください:

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

Learn more in the Delta (マニフェスト) Updatesドキュメント.

autoUpdate は、__CAPGO_KEEP_0__のJavaScriptファイルではなく、ファイル内で設定されています。 capacitor.config.ts file, not in JavaScript code. It supports these values:

false __CAPGO_KEEP_0__ 'off': 自動更新を無効にする
true または 'atBackground' (default): アプリがバックグラウンドに移動したときに自動でダウンロードして適用する
'atInstall': フレッシュインストールまたはネイティブアプリの更新後のみ即時適用、他の場合はバックグラウンドフローを使用する
'onLaunch': アプリ起動時のみ即時適用、起動チェック後はアプリ起動後にバックグラウンドフローを使用する
'always': 自動更新が実行されるたびに即時適用
'onlyDownload': 自動ダウンロード、emit、　、そして次のバンドルを自動設定しない updateAvailableクリップボードにコピー

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 when using instant apply with autoSplashscreen
    },
  },
};

export default config;

__CAPGO_KEEP_0__モードでは、 autoUpdate: 'always', Capgo will immediately apply an update as soon as the download completes during an update check, even if the user is actively using the app. Without periodic checking enabled, this means updates will only be applied when the app starts or resumes from background.

モードでは、 autoUpdate is a native configuration, instant apply modes require some additional handling in your JavaScript code.

モードでは、

Capgo を自動でアップデートをチェックしダウンロードするように設定したいが、自動適用は行わない場合は autoUpdate: 'onlyDownload':

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

このモードではプラグインは updateAvailable バンドルがダウンロードされた後発生します。アプリはその後、 CapacitorUpdater.set() または自分のアップデートの表示を呼び出すときに決定できます。

自動スプラッシュスクリーン処理

インスタント適用モードを簡単に使用できるようにするために、Capgo はバージョン 7.6.0 以降から提供しているオプションがあります。 autoSplashscreen コピー

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

コピー autoSplashscreen は有効になっています:

自動的にアップデートが適用されたときにスプラッシュスクリーンを非表示にします
自動的にアップデートが必要ないときにスプラッシュスクリーンを非表示にします
You don’t need to manually listen for appReady events or call SplashScreen.hide()

Manual Splashscreen Handling

If you prefer manual control or need custom logic, you can disable autoSplashscreen and handle it yourself:

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

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

The appReady event fires once the app has finished initializing and applying any pending updates. This is the point at which it’s safe to show your app’s UI, as it ensures the user will see the latest version.

In addition to handling the appReady event, we recommend setting the keepUrlPathAfterReload configuration option to true when using an instant apply mode. This preserves the current URL path when the app is reloaded due to an update, helping maintain the user’s location in the app and reducing disorientation.

If you don’t handle the appReady event and set keepUrlPathAfterReload when using an instant apply mode, the user may briefly see a stale version of the app, be taken back to the initial route, or see a flicker as the update is applied.

Using an instant apply mode can be useful for delivering critical bug fixes or security patches, but it comes with some tradeoffs:

The user may see a brief flicker or loading state as the update is applied if you don’t properly handle the splashscreen (either with autoSplashscreen or manual appReady event handling).
If the update modifies the app state or UI, the user may see a disruptive change in the middle of a session.
アプリ内でのユーザーの位置が失われる可能性があるため、__CAPGO_KEEP_0__が設定されていない場合。 keepUrlPathAfterReload __CAPGO_KEEP_0__が設定されていないと、ユーザーは混乱する可能性がある。
ユーザーの位置を保存して復元する際には、慎重に取り扱う必要がある。

__CAPGO_KEEP_0__を有効にすると、以下のことをお勧めする。

最も簡単な設定の場合、__CAPGO_KEEP_1__を使用するか、またはカスタムロジックが必要な場合は__CAPGO_KEEP_2__イベントを手動で処理する。 autoSplashscreen: true __CAPGO_KEEP_3__を__CAPGO_KEEP_4__に設定して、ユーザーの位置をアプリ内で保存する。 appReady 必要に応じてアプリの状態を保存して復元し、ユーザーの進捗を失うことなくアプリを更新する。
アプリの更新動作を徹底的にテストし、突然の移行、失われた状態、または混乱を招く位置の変更がないことを確認する。 keepUrlPathAfterReload Instant Applyを有効にすると、以下のことをお勧めする。 true 最も簡単な設定の場合、__CAPGO_KEEP_1__を使用するか、またはカスタムロジックが必要な場合は__CAPGO_KEEP_2__イベントを手動で処理する。
Setting __CAPGO_KEEP_3__ to __CAPGO_KEEP_4__ to preserve the user’s location in the app.
Saving and restoring the app state as needed to avoid losing user progress.

ほとんどの場合、デフォルトの更新動作は、更新を迅速に提供し、混乱を最小限に抑えるバランスがとれることが多い。しかし、特定のニーズを持つアプリでは、Capgoが更新の適用時期と方法をカスタマイズできる柔軟性を提供する。

更新動作から続ける

あなたが使用している 更新動作 を使用して、ライブ更新の配信を計画している場合、__CAPGO_KEEP_0__ Live Updatesと接続してください。 Capgo Live Updates for the product workflow in Capgo Live Updates, __CAPGO_KEEP_0__ Live Updates の実装詳細 Overview の実装詳細、 Update Types Update Typesの実装詳細については Getting Started Getting Startedの実装詳細については