ネイティブ互換性

Capgo live update はアプリの JavaScript バンドル を即座に置き換えますが、変更できないのは ネイティブ アプリのネイティブ部分です。つまり、インストール済みのバイナリにコンパイルされている Capacitor/Cordova プラグイン、ネイティブ依存関係、ネイティブプロジェクト設定です。新しい bundle が、インストール済みのバイナリにないネイティブ code を必要とする場合、その bundle は ネイティブ非互換: Capgo による配信自体は可能ですが、古い Native Build のままのデバイスではクラッシュや予期しない動作が発生する可能性があります。

このページでは、Capgo がネイティブの互換性をどのように検知するか、互換性のないアップデートがユーザーに与える影響、そしてネイティブの変更を安全にリリースする方法を説明します。

注意

Live Updates で更新できるのは JavaScript bundle の変更のみです。プラグインの追加・削除、Capacitor のアップグレード、ネイティブプロジェクトの設定変更など、ネイティブ側の code を更新する必要がある場合は、通常のアプリストア配信プロセスを通じて新しいバイナリビルドを提出する必要があります。

要約: OTA かネイティブか？

Capgo は、生成された web build フォルダからファイルを送信できます。変更内容が HTML、CSS、JavaScript、アセット、またはその出力に含まれる純粋な JavaScript パッケージのみである場合は、live update としてリリースしてください。

変更が次を更新する場合は、ネイティブアプリのリリースを使用してください capacitor.config.ts、Capacitor 設定に保存されているプラグイン設定、ネイティブプラグインや依存関係、Capacitor 自体、または iOS/Android のプロジェクトファイル。実用的な判断基準：その変更が次を通じてネイティブプロジェクトを更新する必要がある場合： npx cap sync または npx cap copy インストール済みのデバイスが利用可能になるまでは、ネイティブとして扱ってください。

変更内容	Capgo によるOTAを利用しますか？	理由
HTML、CSS、アプリのJavaScript、画像、フォント、その他のWebビルド資産	はい	これらは実行時にWeb bundleから読み込まれます。
Web出力にバンドルされた純粋なJavaScriptパッケージの変更	はい	生成されたJavaScriptはWeb bundleの一部です。
capacitor.config.ts 変更	いいえ	Capacitor の設定は、ビルド時にネイティブアプリに読み込まれます。
Capacitor または Cordova プラグインの追加、削除、アップグレード	いいえ	インストール済みのネイティブバイナリに、対応するネイティブ code が含まれている必要があります。
iOS または Android プロジェクトファイルの変更	いいえ	既存のユーザーは、ストアから新しいバイナリを入手する必要があります。

スタック別のクライアントプラグイン

Capgo は、各ハイブリッドランタイム専用のアップデータークライアントを提供しています：

プラグイン	使用シーン
@capgo/capacitor-updater	Capacitor iOS/Android アプリ
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ アプリ
@capgo/electron-updater	Electron デスクトップアプリ

ネイティブ互換性チェックはクライアントプラグインに関係なく適用されます。バンドルに記録されたネイティブ依存関係と、インストール済みのバイナリを比較します。

ネイティブ互換性が重要な理由

すべての Capacitor アプリは2つのレイヤーで構成されています：

• この ネイティブバイナリ ユーザーは App Store / Play Store からインストールします。これには Capacitor、ネイティブプラグイン、ネイティブ設定が含まれます。
• この JavaScript バンドル Capgo が OTA で更新できる（あなたの Web アプリ）

live update は JavaScript レイヤーのみを入れ替えます。もし新しい JavaScript が、インストール済みのバイナリにコンパイルされていないネイティブプラグインや API を呼び出した場合、実行時に呼び出しが失敗し、アプリのクラッシュや機能のサイレントな破損を招く可能性があります。簡単に言うと、Capgo はネイティブの code を更新できないため、古い Native Build で動作しているデバイスでは、新しいネイティブ code を前提にビルドされた bundle を安全に実行することはできません。

Capgo による互換性検知の仕組み

bundle を upload する際、または手動でチェックを実行すると、Capgo は以下の項目を比較します： ネイティブパッケージ ローカルプロジェクト内の（Capacitor/Cordova プラグインとそのバージョン）と、bundle に記録されているネイティブパッケージを比較します。 現在その channel で公開されているもの:

• これらが一致する場合、変更は JavaScript のみであり、 OTA で配信しても安全です.
• プラグインが追加、削除、またはバージョン変更されている場合、その bundle は ネイティブ非互換 — これらの変更は、ユーザーが新しい Native Build をインストールした後にのみ適用されます。

CLI から確認する

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

CLI は、各ネイティブパッケージのローカルバージョン、チャンネル上のバージョン、およびステータスを一覧表示します：

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

ヒント

追加 --text 絵文字を〜に置き換える OK/FAIL （CI ログで便利です）、および --package-json / --node-modules モノレポ内の正しいパスを指定するために。

マシンリーダブルな判定結果を取得 (CI)

パイプラインでは、 bundle releaseType チェック結果を単一の単語に集約します：

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

これを利用してリリースパイプラインを制御できます。次が出力されたら live update を配信し、 OTA次が出力されたら Native Build をトリガーします。 native.

互換性のないアップデートがユーザーに与える影響

注意

デフォルトでは、非互換を検知すると 決して アップロードをブロックします — ネイティブと互換性のない bundle をアップロードし、それをチャンネルのアクティブビルドに設定すると、Capgo は その bundle を配信し、 そのチャンネルのデバイスに届けます。（ハードゲートにするには --fail-on-incompatible — 下記の「 互換性のない配信を防ぐ 」を参照してください。）

まだ古い ネイティブバイナリを実行しているデバイスでは、ネイティブ側の code が不足しているため、アップデートが「正常に」ダウンロード・適用されたにもかかわらず、クラッシュや機能不全が発生する可能性があります。これが、live update が公開・配信されていても既存ユーザーのアプリを壊し得る理由であり、互換性のない bundle が公開されたときに Capgo が警告できる理由でもあります。

Capgo の 自動ロールバック 実行前にスローされたJavaScriptエラーは検知できますが、 notifyAppReady() 実行されますが、互換性のあるネイティブcodeを配布する代わりにはなりません。後からクラッシュするような不一致や、ネイティブ側でクラッシュするケースは、これをすり抜ける可能性があります。

ネイティブの変更を安全にリリースする方法

新しいNative Buildを公開する（根本的な解決策）

bundleに新しいネイティブcodeが必要な場合は、新しいバイナリをビルドしてApp Store / Play Storeに提出してください（またはCapgo Cloud Buildで再ビルドします）。ユーザーがバイナリをアップデートすれば、bundleのネイティブ依存関係が一致し、live updateが正しく動作するようになります。

互換性のないbundleが既に配信中の場合のロールバック

チャンネルで互換性のないbundleが既にアクティブな場合は、ネイティブビルドがリリースされるまでその配信を止めるため、チャンネルを最後に互換性のあったビルドに戻してください。詳細は ロールバック.

互換性のない配信を防ぐ

ネイティブパッケージを検証する、2つの補完的なガード機能があります：

CIでのアップロードを失敗させる — --fail-on-incompatible

にフラグを追加します。 bundle upload ステップ。バンドルのネイティブパッケージが、チャンネルの現在配信中のバージョンと一致しない場合、アップロードは 非ゼロの終了コードで失敗し、何も配信されません 。これにより、ユーザーが Native Build をインストールするまで適用できない OTA アップデートを、気づかないうちに公開してしまうのをパイプラインが防ぎます：

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

互換性のあるアップロード、およびチェックが実行できないケース（新しいチャンネルやリモートメタデータがない場合）は、そのまま通過します。対話型ターミナルでは、代わりに Capgo Builder の native-build フローが提案され、拒否すると失敗します。（以下とは併用できません --ignore-metadata-check.)

ヒント

特定のケースで 意図的に チャンネルのライブネイティブパッケージとは異なるbundle（新しいpluginやCapacitorのアップグレードなど）が必要な場合は、 --fail-on-incompatible そのベースラインのアップロード時に省略してください。通常のOTA CIではフラグを有効にしたままにします。フルチャンネルワークフロー： Native + OTA チャンネルのワークフロー.

ネイティブバージョンによる配信制御 — metadata + --auto-min-update-version

特定のケースで do Native Buildとbundleを同時にリリースし、チャンネルを metadata 戦略と、〜でのアップロード --auto-min-update-version. Capgo はアップロードのたびに互換性チェックを実行し、bundle に新しいネイティブ code が必要な場合は update floor を引き上げて、対応するネイティブ build が未インストールのデバイスに配信されないようにします:

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

注意

次のようなバージョン番号ルール、 --disable-auto-update major は 決して 代わりにはなりません — これらはバージョンのジャンプをブロックするだけで、ネイティブ code を検査しないため、マイナーやパッチリリースに含めたネイティブ変更も配信されてしまいます。ネイティブパッケージをチェックするには、 --fail-on-incompatible または --auto-min-update-versionを使用してください。

詳細は バージョンターゲティング ターゲティングオプションの全項目については

関連情報

ネイティブ + OTA ワークフロー

Dev/production チャンネルと、保持すべきタイミング、 --fail-on-incompatibleおよび意図したネイティブベースラインを配信する方法。

OTA / Native 自動切替

連携 bundle releaseType GitHub Actions や GitLab と連携し、CI が live update と Capgo Build のどちらを選ぶようにします。

バージョンターゲティング

チャンネル、semver ルール、メタデータ戦略を使って、互換性のある bundle だけを配信します。

ロールバック

互換性のないbundleが配信された場合、チャンネルを最後に互換性があったbuildへ戻します。

アップデートの種類

タイミング、遅延条件、およびバージョンブロックの連携方法について。

CLI: bundle

bundleの互換性、releaseType、およびuploadオプションのリファレンス。

Native Compatibility から続ける

使用している場合 ネイティブ互換性 Live Updateを安全に運用するために、以下と連携させてください： バージョンターゲティング ネイティブバージョンごとにbundleをルーティングする方法、 ロールバック 互換性のないbundleが配信されたときのリカバリ方法、 アップデートの種類 チャネルのバージョンブロッキングの仕組み、および Capgo CLI bundleリファレンスは compatibilityおよびreleaseTypeコマンドについて解説しています。