ネイティブ互換性

A Capgo ライブアップデートはアプリの JavaScript バンドル を即時置き換えますが、 ネイティブ part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is __CAPGO_KEEP_0__/Cordova プラグイン、ネイティブ依存関係、ネイティブプロジェクト構成: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

ネイティブ互換性のない

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

このページでは、__CAPGO_KEEP_0__ がネイティブ互換性を検出する方法、ユーザーに不互換なアップデートが何を意味するか、ネイティブ変更を安全に配信する方法について説明します。

Capgo から生成されたウェブビルドフォルダからファイルを送信できます。変更が HTML、CSS、JavaScript、資産、またはその出力に組み込まれた純粋な JavaScript パッケージに影響を与える場合、ライブアップデートとして送信してください。

ネイティブアプリリリースを使用する必要があります。 capacitor.config.ts、プラグインの構成が Capacitor の構成、ネイティブプラグインまたは依存関係、 Capacitor 自身、または iOS/Android プロジェクトファイルを更新します。実用的なチェック: 変更がネイティブプロジェクトを更新する必要がある場合、ネイティブアプリリリースを使用してください。 npx cap sync または npx cap copy before installed devices can use it, treat it as native.

context	Ship with Capgo OTA?	Why
HTML, CSS, app JavaScript, images, fonts, and other web build assets	Yes	They are loaded from the web bundle at runtime.
JavaScriptパッケージの変更が、Web出力にバンドルされます。	はい	生成されたJavaScriptはWebバンドルの一部です。
capacitor.config.ts 変更	いいえ	Capacitorの設定はビルド時にネイティブアプリに読み込まれます。
Adding, removing, or upgrading Capacitor/Cordova plugins	いいえ	The installed native binary must contain the matching native code.
iOSまたはAndroidプロジェクトファイルの変更	いいえ	既存のユーザーには、ストアから新しいバイナリを取得する必要があります。

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

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

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

クライアント プラグインに関係なく、ネイティブの互換性チェックは実行されます。 — これらは、インストール済みバイナリと比較して、パッケージの記録されたネイティブ依存関係を確認します。

ネイティブの互換性の重要性

すべてのCapacitorアプリは2つの層で配信されます:

• The native binary users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• The JavaScript bundle (your web app) that Capgo can update over the air.

A live update swaps only the JavaScript layer. If that new JavaScript calls a native plugin or API that isn’t compiled into the installed binary, the call fails at runtime — which can crash the app or silently break a feature. Put simply: Capgo cannot update native code, so a device running the old native build can’t safely run a bundle that was built against new native code.

How Capgo detects compatibility

When you upload a bundle — or run the check manually — Capgo compares the native packages in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle 現在のチャンネルで実行中:

• もしマッチしたら、変更はJavaScriptのみで 安全にオーバー・ザ・エアで配信可能.
• プラグインが追加、削除、またはバージョンが変更された場合、バンドルは ネイティブ非互換 — その変更はユーザーが新しいネイティブバイナリをインストールするまで効果が生じない

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

Tip

追加 --text を入れ替えるための絵文字を入れ替える OK/FAIL CIログで便利なので、(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

リリースパイプラインをこのゲートで制御する: 互換性のないライブアップデートを出力するときにアップロードする OTA、そして、出力するときにネイティブビルドをトリガーする native.

互換性のないアップデートとはユーザーにとって何が意味するか

注意

デフォルトでは、不互換性を検出することは アップロードをブロックしない — ネイティブ不互換のバンドルをアップロードし、そのチャンネルのアクティブビルドとして設定した場合、__CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo デバイスに配信する — 以下を参照 --fail-on-incompatible __CAPGO_KEEP_0__ 不互換の配信を防止する 以下の説明を参照してください。

まだ古いネイティブバイナリを実行しているデバイスでは 古いネイティブバイナリを実行しているデバイスでは, the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo の 自動的なロールバック 実行される前にスローされた JavaScript エラーをキャッチできますが、それはネイティブの__CAPGO_KEEP_0__の互換性の問題を解決するための代替手段ではありません。 notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

セクションのタイトルは “ネイティブの変更を安全に配信する方法”

Publish a new native build (the real fix)

バンドルが新しいネイティブcodeが必要な場合、App Store / Play Storeに新しいバイナリを提出し、またはCapgo Cloud Buildで再構築してください。ユーザーがバイナリを更新すると、バンドルのネイティブ依存関係が整い、ライブアップデートが正しく実行されます。

既存のライブアップデートが不互換のバンドルがすでに活性化されている場合に戻す

既にチャンネルで活性化されている不互換のバンドルがある場合、チャンネルを最後の互換性のあるビルドに戻して、ネイティブビルドが出るまで配信を停止してください。詳しくは ロールバック.

不互換の配信を防ぐ

2つの補完的なガード、どちらも実際にはネイティブパッケージを検査します:

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

ステップにフラグを追加してください。バンドルのネイティブパッケージがチャンネルの現在のライブバージョンと一致しない場合、アップロード bundle upload ステップにフラグを追加してください。バンドルのネイティブパッケージがチャンネルの現在のライブバージョンと一致しない場合、アップロード __CAPGO_KEEP_0__で失敗し、ゼロ以外のエラーが発生し、配信されない — したがって、パイプラインは、ユーザーがネイティブビルドをインストールするまで、有効になるまでのOTAアップデートを静かに公開するのを防ぐ

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

互換性のあるアップロード — そしてチェックを実行できないケース (新しいチャネル、またはリモートメタデータがない) — は変更されずに通過する。インタラクティブなターミナルでは、Capgo Builderネイティブビルドフローを提示する;却下すると失敗する。 (これは --ignore-metadata-check.)

ヒント

ヒント あなたが need a bundle that differs from the channel’s live native packages (new plugin, Capacitor upgrade, and so on), omit --fail-on-incompatible 必要なのは、チャンネルのライブネイティブパッケージとは異なるバンドルが必要な場合 (新しいプラグイン、__CAPGO_KEEP_0__のアップグレード、など) です。そうした場合、基準のアップロードを省略してください。毎日、OTA CIでフラグを維持してください。フルチャンネルワークフロー: ネイティブ + OTA チャンネルワークフロー.

ネイティブ版の配信 — metadata + --auto-min-update-version

あなたが する ネイティブビルドとバンドルを一緒に配信する場合、 metadata 戦略にチャンネルを設定し、 --auto-min-update-versionCapgoはアップロードごとに互換性チェックを実行し、バンドルが新しいネイティブcodeが必要な場合、対応するネイティブビルドがインストールされていないデバイスがアップデートを受け取らないようにアップデートフロアを上げます:

# 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 は not a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible or --auto-min-update-versionVersion Targeting

for the full set of targeting options. Related Native + OTA Workflow

Dev/production channels, when to keep

See

Version Targeting --fail-on-incompatible, which check your native packages.

Auto OTA or Native

Wire bundle releaseType GitHubアクションまたはGitLabにワイヤーします。CIはライブアップデートを検出するか、Capgoビルドを検出します。

バージョン対象

バージョン対象

互換性のあるバンドルのみを、チャンネル、semver規則、およびメタデータ戦略を使用して配信します。

ロールバック

チャンネルを最後の互換性のあるビルドに戻します。互換性のないバンドルがライブに公開された場合。

アップデートの種類

CLI: bundle

__CAPGO_KEEP_0__

バンドル互換性、リリースタイプ、およびアップロードオプションのリファレンスです。

あなたは「ネイティブ互換性」を使用している場合 「ネイティブ互換性」 「バージョン対象設定」という機能を使用して、ライブアップデートを安全に保証するには、 「バージョン対象設定」 ネイティブのバージョンに基づいてバンドルをルーティングする ロールバック 不互換のバンドルが配信されたときに復旧する アップデートの種類 チャンネルバージョンブロッキングを理解し、 「Capgo」「CLI」バンドル参照 互換性とリリースタイプのコマンドのための