capgo-live-updates

Capgo Live Updates

@capgo/capacitor-updater を Capacitor アプリに組み込み、最初のバンドルを配信し、安全にロールバックできるようにします。

以下の情報は、@capgo/capacitor-updater 8.52 および @capgo/cli 8.77 に基づいて確認済みです（2026 年 10 月）。

使用するタイミング

次の場合に使用します。

• ユーザーが Capacitor アプリで OTA／ライブアップデート、ストア審査なしのホットフィックス、または「Capgo」を求めている場合。
• アップデータープラグインのインストール、アップグレード、または capacitor.config.* での設定が必要な場合。
• ユーザーが notifyAppReady、autoUpdate モード、directUpdate、autoSplashscreen、setChannel、getLatest、download、next、set、または reset について質問している場合。
• アップデートのアップロードは正常に完了するものの、デバイスに適用されない、ロールバックされる、またはループする場合。

次の場合は使用しないでください。

• 作業が CLI によるバンドル、チャネル、段階的配信、または暗号化キーのコマンドのみの場合。capgo-release-management を使用してください。
• ユーザーが Capgo Cloud から署名済み IPA／APK／AAB を必要としている場合。capgo-native-builds を使用してください。
• ユーザーが Capawesome Cloud（capawesome-live-update-migration）または Ionic Appflow（ionic-appflow-migration）から移行する場合。
• ユーザーがリリースパイプライン全体（OTA、ネイティブビルド、ストアへの公開）を求めている場合。capgo-release-workflows を使用してください。
• リクエストが一般的な CLI の振り分けや MCP のセットアップについての場合。capgo-cli-usage を使用してください。

リファレンス一覧

トピックが該当する場合にのみ、リファレンスを読み込んでください。

ファイル	読み込むタイミング
references/configuration.md	capacitor.config.* の plugins.CapacitorUpdater の編集、autoUpdate モードの選択、セルフホスト URL の設定
references/js-api.md	手動アップデートフロー、リスナー、チャネルの切り替え、ロールバックコードの作成
references/channels-and-rollouts.md	チャネル、デバイスの自己割り当て、段階的配信、バージョン指定
references/ci-cd.md	GitHub Actions、GitLab CI、またはその他の CI からのアップロード
references/troubleshooting.md	デバイスがアップデートされない、ロールバックされる、またはバックエンドがエラーコードを返す場合

バージョン規則（最初に読む）

アップデーターのメジャーバージョンは Capacitor のメジャーバージョンに対応します。

Capacitor	インストール
8.x	npm install @capgo/capacitor-updater@latest（8.x 系）
7.x	npm install @capgo/capacitor-updater@lts-v7
6.x	npm install @capgo/capacitor-updater@lts-v6
5.x	npm install @capgo/capacitor-updater@lts-v5
4.x	npm install @capgo/capacitor-updater@lts-v4

Capacitor 9 に関する注意：Capacitor 9 はまだプレリリース版（@capacitor/core@next）です。2026 年 10 月時点では、Capacitor 9 対応のアップデーター系統はありません。8.x 系の宣言では、peerDependencies: @capacitor/core ^8.0.0 が指定されています。npm の @capgo/[email protected] は、2023 年にリリースされた古い Capacitor 5 向けバージョンで、非推奨とされているため、Capacitor 9 用にインストールしてはいけません。Capacitor 9 のプロジェクトについて案内する前に、npm view @capgo/capacitor-updater dist-tags で現在のタグを確認してください。Capacitor 9 の系統が一覧にない場合は、その旨をユーザーに伝えてください。

シークレットと確認

• Capgo API キー、署名パスワード、.p8 キー、キーストア、またはサービスアカウントの JSON をチャットに貼り付けるよう、ユーザーに求めてはいけません。npx @capgo/cli@latest login を自分で実行してもらうか（ブラウザーが開くか、マスクされたプロンプトでキーの入力を求められます）、シェルまたは CI のシークレットストアで CAPGO_TOKEN を設定してもらってください。
• コマンド引数にシークレットを含めないでください。シェルの履歴やプロセス一覧に残ります。環境変数、保存済みログイン、または CLI の対話型プロンプトを使用してください。
• それでも会話にシークレットが現れた場合、繰り返したり、ファイルに書き込んだりせず、失効させて新しいものを作成するようユーザーに伝えてください。
• npx @capgo/cli@latest は、npm から最新の CLI をダウンロードして実行します。ユーザーのプロジェクト内で、ユーザーの許可を得てからのみ実行してください。CI では正確なバージョンを固定してください。
• リモートの状態を変更するコマンドを実行する前に確認を取ってください。対象には、バンドルのアップロード、チャネルの変更や昇格、アプリ、バンドル、チャネル、キーの削除、ストアにアップロードするビルドのリクエスト、認証情報のエクスポートや削除が含まれます。どのアプリとチャネルに対して何が変更されるかを説明してください。

手順

1. 編集前に確認する

• package.json を読み、@capacitor/core のメジャーバージョンと、既存の @capgo/capacitor-updater があるかを確認します。
• capacitor.config.ts|json を読み、appId、webDir、既存の plugins.CapacitorUpdater があるかを確認します。
• アプリのエントリーポイント（main.ts、main.tsx、App.vue の setup、app.component.ts など）を探します。ここに notifyAppReady() を配置します。
• ほかの OTA SDK がないか確認します。存在する場合は作業を中止し、対応する移行スキルに切り替えます。

2. プロジェクトを接続する（推奨手順）

ガイド付きオンボーディングでは、アプリの登録、プラグインのインストール、エントリーポイントのパッチ適用、ビルド、アップロード、デバイスでの検証を行います。

npx @capgo/cli@latest init

ユーザーにターミナルで実行してもらいます。ブラウザー経由でサインインする（または login で保存したキーを使用する）ほか、アプリ ID を尋ね、最初のバンドルをアップロードするため、事前に許可を得てください。チャットで API キーを尋ねないでください。モノレポでは、--package-json、--main-file、--capacitor-config を追加します。

3. 手動でインストールする（init を使用しない場合）

npm install @capgo/capacitor-updater@latest   # pick the tag from the Version Rule table
npx cap sync
npx @capgo/cli@latest app add com.example.app

最小構成の設定（autoUpdate のデフォルトは true で、これは "atBackground" と同じです）：

plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
  },
},

4. すぐに notifyAppReady() を呼び出す

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

CapacitorUpdater.notifyAppReady();

• エントリーファイルの先頭で、ネットワーク呼び出しや非同期初期化より前に呼び出します。appReadyTimeout（デフォルトは 10000 ms）以内に呼び出されない場合、バンドルは失敗と判定され、前のバンドルに復元されます。
• この呼び出し後にクラッシュや API エラーが発生しても、ロールバックは実行されません。
• bundle upload はこの呼び出しをチェックし、notifyAppReady() is missing in the build folder (...) というエラーで失敗します。ソースを修正してください。ロールバックのリスクをユーザーが受け入れる場合に限り、--ignore-notify-app-ready / --no-code-check を使用してください。

5. バンドルをリリースする

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production

即時適用モード（"atInstall"、"onLaunch"、"always"）では、--delta を指定してアップロードし、@capacitor/splash-screen の launchAutoHide: false とともに autoSplashscreen: true を設定します。references/configuration.md を参照してください。

6. リリースごとに OTA かネイティブかを判断する

OTA で変更できるのは Web アセットのみです。新しいネイティブプラグインの追加やアップグレード、Capacitor の更新、ios/、android/、ネイティブ設定内の編集には、ストアビルドが必要です。次のコマンドで確認します。

npx @capgo/cli@latest bundle releaseType com.example.app --channel production   # prints OTA or native

releaseType が比較するのは、ネイティブパッケージのメタデータのみです。ios/ や android/ 内の直接編集は検出できません。

注意点

• ストアのコンプライアンス： OTA で変更できるのは、インタープリタ型の Web コードとアセットのみであり、アプリの主な目的を変更してはいけません。これは、Apple Developer Program License Agreement のインタープリタ型コードに関する条項、App Review Guideline 2.5.2、および Google Play の Device and Network Abuse ポリシーに基づいています。審査が必要な機能のリリースに OTA を使用しないでください。また、アプリの使用をブロックするためにアップデートを強制しないでください。
• プライバシーマニフェスト： iOS では、PrivacyInfo.xcprivacy に理由 CA92.1 とともに NSPrivacyAccessedAPICategoryUserDefaults が必要です。
• 設定キーは privateKey ではなく publicKey です。 秘密鍵（.capgo_key_v2）はアップロードする側で管理し、アプリやリポジトリに絶対に含めないでください。
• resetWhenUpdate（デフォルトは true） は、新しいネイティブビルドのインストール時にダウンロード済みバンドルをクリアします。これを無効にすると、OTA バンドルより古いストアビルドで問題が発生する可能性があります。
• 開発用ビルドでのテスト： チャネルでは、フラグ（disable_dev_build、disable_emulator など）によって開発用、エミュレーター、または本番デバイスがブロックされます。プラグインが壊れていると判断する前に、チャネルのオプションを確認してください。
• ライブリロード（Ionic/Quasar）： アップデーターはライブリロードの URL を配信しません。アップデートのテスト時はライブリロードを無効にしてください。
• set() は JS コンテキストを破棄します。 その後のコードは実行されません。次のバックグラウンド時に適用するには、next() を優先してください。
• 暗号化は秘匿性を意味しません： 暗号化されていないバンドルは公開 Web アセットです。暗号化はストレージと配信を保護しますが、公開鍵はアプリに含まれます。key create / key save については capgo-release-management を参照してください。

検証

1. npx @capgo/cli@latest doctor を実行すると、インストールされているアップデーターのバージョンが表示され、古くなっているものがあれば警告されます。
2. grep -rn "notifyAppReady" src/ を実行し、エントリーポイントに早期に呼び出される箇所が1つだけ見つかることを確認します。
3. npx cap sync が成功したら、実際のデバイスでネイティブアプリを一度ビルドしてインストールします。
4. 目に見える変更を加えたバンドルをアップロードします。アプリをバックグラウンドに移動して再度開きながら、npx @capgo/cli@latest app debug com.example.app を実行します。ログにチェック、ダウンロード、set が表示されるはずです。
5. npx @capgo/cli@latest probe --platform ios（または android）を実行すると、この設定に対してバックエンドがアップデートを配信するかどうかと、配信されない理由が表示されます。

エラー処理

症状／文字列	修正方法
notifyAppReady() is missing in the build folder	エントリーポイントに呼び出しを追加し、再ビルドしてから再度アップロードします
index.html is missing in the root folder of <dir>	--path の指定先が誤っています。ビルド済みの webDir を使用します
no_new_version_available	正常です。デバイスはすでに最新です
disable_auto_update_to_major / _minor / _patch	チャネルの戦略によって更新がブロックされています。CapacitorUpdater.version を合わせるか、--disable-auto-update を変更します
cannot_update_via_private_channel	チャネルでセルフ割り当てを有効にします（channel set <ch> --self-assign）
on_premise_app（HTTP 429）	appId が Capgo に登録されていない、アプリにオンプレミスのフラグが設定されている、またはプランがキャンセルされています
アップデートがダウンロードされた後、次回起動時に元に戻る	notifyAppReady() の実行が遅すぎるか、実行されていません。または、実行前にバンドルで例外が発生しています

コード一覧の全文は references/troubleshooting.md にあります。

リソース

• はじめに：https://capgo.app/docs/getting-started/add-an-app/
• プラグインの設定：https://capgo.app/docs/plugins/updater/settings/
• プラグイン API：https://capgo.app/docs/plugins/updater/api/
• アップデートの動作：https://capgo.app/docs/live-updates/update-behavior/
• よくある問題：https://capgo.app/docs/plugins/updater/commonproblems/