Native互換性

Capgoライブアップデートは、Capgoのアプリの JavaScriptバンドル 即時置き換えますが、__CAPGO_KEEP_0__/Cordovaプラグイン、ネイティブ依存関係、ネイティブプロジェクト構成がコンパイルされたインストール済みバイナリに含まれる ネイティブ 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は、Capgoが提供する更新を実行できますが、古いネイティブビルドを実行しているデバイスでは、クラッシュまたは不正動作が発生する可能性があります。

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

Note

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

native互換性の重要性

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

• 「The」 nativeバイナリ ユーザーがApp Store / Play Storeからインストールするものです。Capacitor、nativeプラグイン、およびnative構成が含まれます。
• 「The」 JavaScriptバンドル (あなたのウェブアプリ)がCapgoでオンエアで更新できるものです。

ライブ更新は、JavaScript層のみを交換します。新しいJavaScriptがインストール済みのバイナリに組み込まれていないnativeプラグインまたはAPIを呼び出す場合、呼び出しは実行時で失敗します。これにより、アプリがクラッシュしたり、機能が静かに破壊されたりします。簡単に言えば、Capgoはnative codeを更新できず、古いnativeビルドを実行中のデバイスでは、new native 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 モノレポで正しいパスを指す

機械読み取り可能な判定結果 (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__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo そのチャンネルのデバイスに配信します。 (この機能をハードゲートに変えることができます — — 以下の「不適切な配信を防ぐ」を参照してください。) --fail-on-incompatible 古いnativeバイナリを実行しているデバイスでは、__CAPGO_KEEP_0__が欠落しているため、クラッシュや機能の不具合が発生する可能性があります — それでもアップデートはダウンロードされ、適用されたと表示されます。 これは、ライブアップデートがライブで配信されていても、既存のユーザーにとってアプリが破損する原因となるため、__CAPGO_KEEP_1__は不適切なbundleがライブになったときに警告を表示します。 __CAPGO_KEEP_0__の自動ロールバック will deliver it

to devices on that channel. On devices still running the, 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.

the missing native Capgo 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_KEEP_1__ can warn you when an incompatible bundle goes live. JavaScriptのエラーをキャッチできる 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.

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

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

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

既存のチャネルに互換性のないバンドルがすでに活性化されている場合にロールバックする

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

不互換な配信を防ぐ

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

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.)

when metadata + --auto-min-update-version

you native ビルドとバンドルを一緒に送信し、チャンネルを戦略とアップロードする __CAPGO_KEEP_0__ がアップロードごとに互換性チェックを実行し、バンドルが新しいnative __CAPGO_KEEP_1__ が必要な場合、対応するnative ビルドがインストールされていないデバイスがアップデートを受け取らないようにアップデートフロアを上げる 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

は

そうではない --disable-auto-update major バージョンジャンプをブロックするだけであり、native __CAPGO_KEEP_0__ を検査することはないので、メジャーまたはパッチリリースにnative 変更が含まれる場合でも配信される 使用 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 または --auto-min-update-version、nativeパッケージを確認するために

See バージョン対象 対象のバージョンをすべて表示するためのオプションのセットを参照してください。

関連

バージョン対象

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

ロールバック

チャンネルを互換性のあるビルドに戻します。

更新タイプ

How __CAPGO_KEEP_0__: apply timing, delay conditions, and version blocking work together.

CLI: bundle

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

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

ネイティブ互換性を使用してライブ更新を安全に保つ場合、 バージョン対象設定 ネイティブのバージョンに基づいてバンドルをルーティングする ロールバック 不互換のバンドルが配信された場合に復元する __CAPGO_KEEP_0__: bundleの互換性、リリースタイプ、およびアップロードオプションのリファレンス ネイティブ互換性から続ける アップデートのタイプ チャンネルバージョンのブロッキングを理解し、 Capgo CLI バンドル参照 互換性とリリースタイプ コマンドのための