Native Compatibility

Capgo ライブアップデートは、 Capgo アプリのJavaScriptバンドルを即時置き換えますが、 Capgo / Cordova プラグイン、ネイティブ依存関係、およびインストール済みバイナリに組み込まれたネイティブプロジェクト構成を変更することはできません。新しいバンドルがインストール済みバイナリにないネイティブ __CAPGO_KEEP_1__ を期待している場合、バンドルはネイティブ非互換です インストール 同期 ソースガイド 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 はまだ機能するかもしれませんが、古いネイティブビルドが実行されているデバイスではクラッシュまたは不正動作が発生する可能性があります。

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

注意

ライブアップデートは、JavaScript バンドル変更に限られます。JavaScript バンドル以外の変更（code に追加または削除されたプラグイン、Capacitor のアップグレード、またはネイティブプロジェクトの構成変更）が必要な場合は、通常のアプリストア配布プロセスを通じて新しいバイナリビルドを提出する必要があります。

TLDR: OTA またはネイティブ?

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

ネイティブアプリリリースを使用する必要があるのは、変更が capacitor.config.ts, plugin configuration stored in Capacitor config, native plugins or dependencies, Capacitor itself, or iOS/Android project files. A practical check: if the change must update the native project through npx cap sync インストール済みのデバイスが使用できるようにする前に、ネイティブプロジェクトを更新する必要がある場合です。実用的なチェック: 変更がネイティブプロジェクトを更新する必要がある場合は、ネイティブと扱ってください。 npx cap copy before installed devices can use it, treat it as native.

変更	Capgo OTAで配信するか?	なぜ
HTML、CSS、アプリケーション JavaScript、画像、フォント、他の Web ビルド アセット	はい	実行時には Web バンドルから読み込まれます。
Pure-JavaScript パッケージの変更が Web 出力にバンドルされます。	はい	生成された JavaScript は Web バンドルの一部です。
capacitor.config.ts 変更	いいえ	Capacitor の設定はビルド時にネイティブ アプリに読み込まれます。
プラグインの追加、削除、またはアップグレード Capacitor/Cordova プラグイン	いいえ	code のインストール済みネイティブバイナリには、対応するネイティブ code が含まれている必要があります。
iOS または Android プロジェクトファイルの変更	いいえ	既存のユーザーは、ストアから新しいバイナリを取得する必要があります。

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

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

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

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

なぜネイティブ互換性が重要か

Capacitor のすべてのアプリは、2 つの層で配布されます。

• 「 ネイティブバイナリ ユーザーは App Store / Play Store からインストールします。Capacitor、ネイティブ プラグイン、およびネイティブ設定が含まれます。
• 「 JavaScript バンドル (Capgo が更新できるウェブアプリ)

A live updateはJavaScript層のみを交換します。新しいJavaScriptがインストール済みバイナリに組み込まれていないネイティブプラグインまたはAPIを呼び出す場合、実行時には呼び出しは失敗し、エラーでアプリがクラッシュしたり、機能が静かに破壊されたりします。簡単に言えば、Capgoはネイティブcodeを更新できず、古いネイティブビルドを実行しているデバイスでは、codeのネイティブに対してビルドされたバンドルを安全に実行できません。

Capgoが互換性を検出する方法

バンドルをアップロードしたり、手動でチェックしたりすると、Capgoは ローカルプロジェクト内のネイティブパッケージ (プロジェクト内のCapacitor/Cordovaプラグインとそのバージョン)を 現在のチャンネルでライブ中のネイティブパッケージ:

• と比較します。 一致すると、変更は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

ヒント

追加 --text エモジを入れ替すには OK/FAIL CIログで便利です。また、モノレポで正しいパスを指すには --package-json / --node-modules __CAPGO_KEEP_0__

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.

ネイティブビルドを実行するときに

注意

デフォルトでは、不互換性を検出してもアップロードをブロックしない — native-incompatible bundleをアップロードし、そのチャンネルのアクティブビルドとして設定した場合、__CAPGO_KEEP_0__はそのチャンネルのデバイスに配信する。 not block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo 古いnativeバイナリを実行中のデバイスでは、__CAPGO_KEEP_0__が欠けているとクラッシュや機能が壊れることがある — それでもアップデートがダウンロードされ「成功」したように見える。 これがなぜライブアップデートがライブ配信されていても既存のユーザーにとってアプリが壊れることがあるのか、そしてなぜ__CAPGO_KEEP_1__が不互換バンドルがライブ配信されたときに警告するのかを理解する。 --fail-on-incompatible __CAPGO_KEEP_0__の __CAPGO_KEEP_1__の __CAPGO_KEEP_0__の

__CAPGO_KEEP_1__の __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 エラーをキャッチできる notifyAppReady() 実行されるが、ネイティブ互換性のある code を置き換えることはできない。後でクラッシュする、またはクラッシュするネイティブの場合、そこに逃げることができる。

ネイティブの変更を安全に配信する方法

新しいネイティブのビルドを公開 (実際の修正)

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

既存のライブに不互換のバンドルがすでに存在する場合、ロールバック

既存のチャネルに不互換のバンドルがすでに存在する場合、チャネルを最後の互換性のあるビルドに戻して、ネイティブのビルドが出るまで配信を停止する。参照 ロールバック.

不相容の配信を防止する

両方の補完的なガード、実際にはネイティブパッケージを検査します:

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

旗をあなたの bundle upload ステップに追加します。 バンドルのネイティブパッケージがチャンネルの現在のライブバージョンと一致しない場合、アップロード ゼロ以外のエラーで失敗し、配信されないため、パイプラインは静かに公開するOTAアップデートを実行しないようにします: ターミナル画面

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

Compatible uploads — and cases where the check can’t run (a new channel, or no remote metadata) — pass through unchanged. In an interactive terminal it offers the Capgo Builder native-build flow instead; declining fails. (Can’t be combined with --ignore-metadata-check.)

CIでアップロードを失敗させる — metadata + --auto-min-update-version

When you do, native build and bundle are shipped together, and the channel is set to the strategy and uploaded with __CAPGO_KEEP_0__. __CAPGO_KEEP_1__ はアップロードごとに互換性のチェックを実行し、バンドルが新しいネイティブ __CAPGO_KEEP_1__ を必要とする場合、対応するネイティブ ビルドがインストールされていないデバイスがアップデートを受け取らないように、更新フロアを上げます。 Terminal window クリップボードにコピー metadata 注意 --auto-min-update-version. Capgo runs the compatibility check on every upload and, when a bundle needs new native code, raises the update floor so devices that haven’t installed the matching native build don’t receive it:

# 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

strategy

__CAPGO_KEEP_0__ --disable-auto-update major __CAPGO_KEEP_1__ are 代替手段 — これらはバージョンジャンプのみをブロックし、ネイティブのcodeを検査することはないので、ミニマムまたはパッチリリースでネイティブの変更が送信されても、送信される。 --fail-on-incompatible または --auto-min-update-version,

これらは、ネイティブのパッケージを確認します。 参照してください バージョン対象

バージョン対象

バージョン対象

バージョン対象

バージョン対象

バージョン対象

アップデートのタイプ

タイミング、遅延条件、バージョンブロッキングの組み合わせのしくみ

CLI: バンドル

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

ネイティブ互換性から続ける

Capgoを使用している場合 ネイティブ互換性 ライブアップデートを安全に保つために、バージョン目標と接続してください バージョン目標 ネイティブバージョンに基づいてバンドルをルーティングするために使用します ロールバック 不互換のバンドルが配信されたときに復元する 更新タイプ チャンネルバージョンブロッキングを理解し、 Capgo CLI バンドル参照 互換性とリリースタイプコマンドのために