ネイティブ互換性

このプラグインの設定用の質問とインストール手順、そしてマークダウンガイドをコピーする。

Capgo live updateは、 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__: Capgo は古いネイティブビルドを実行しているデバイスではクラッシュまたは不正動作する可能性があります。

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

OTA またはネイティブ?

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

ネイティブアプリリリースを使用する必要がある変更は、 capacitor.config.ts、Capacitorの構成、ネイティブプラグインまたは依存関係、Capacitor自体、またはiOS/Androidプロジェクトファイルの更新です。実用的なチェック: 変更がネイティブプロジェクトを更新する必要がある場合、 npx cap sync または npx cap copy 変更

Change	Capgo OTAで配信するか	context
HTML, CSS, アプリケーション JavaScript, 画像, フォント, その他の Web ビルドアセット	はい	Capgo のソリューションマーケティングページ
はい	はい	Web バンドルから実行時に読み込まれます。
`capacitor.config.ts` changes	No	Capacitor 設定はビルド時にネイティブアプリに読み込まれます。
Capacitor/コルダバプラグインの追加、削除、またはアップグレード	No	code の設定はビルド時にネイティブアプリに読み込まれます。
iOSまたはAndroidプロジェクトファイルの変更	No	既存のユーザーは、ストアから新しいバイナリを取得する必要があります。

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

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

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

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

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

Every Capacitor app ships in two layers:

ライブアップデート ネイティブバイナリ App Store / Play Store からユーザーがインストールします。それには、Capacitor、ユーザーのネイティブプラグイン、およびネイティブの設定が含まれます。
ライブアップデート JavaScript バンドル (あなたのウェブアプリ) が Capgo をオンエアで更新できるものです。

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

How Capgo detects compatibility

アップロードしたバンドル — または、手動でチェックを実行する — 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

マシンが読める判定結果を取得(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 を出力するときに live update を出荷する OTA, native ビルドをトリガーするときに表示されます。 native.

ネイティブビルドをトリガーするには、__CAPGO_KEEP_0 を出力するときに CAPGO_KEEP_0__ を出荷します

古いネイティブバイナリを実行しているデバイスでは、 __CAPGO_KEEP_0__ が欠けている場合、クラッシュや機能が破損する可能性があります。 — これは、更新がダウンロードされ適用された「成功」でしたが、クラッシュや機能の破損につながる可能性があります。これは、__CAPGO_KEEP_1__ がライブで配信されていても、既存のユーザーにとってアプリを破損させる可能性があるためです。また、__CAPGO_KEEP_2__ は、非互換のバンドルがライブになったときに警告を表示することができます。, 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’s は、実行される前にスローされる JavaScript エラーをキャッチできますが、ネイティブの __CAPGO_KEEP_0__ が互換性のあるものであることを保証することはできません。 — これは、後でクラッシュしたり、ネイティブでクラッシュしたりする可能性のある不一致を逃すことができます。 __CAPGO_KEEP_1__ notifyAppReady() nativeアプリケーションが動作するが、互換性のあるnative codeを配信する代替手段ではない。

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

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

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

既存のインコンプレティブバンドルがすでにライブになっている場合にロールバック

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

互換性のない配信を防ぐ

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

GitHub metadata + --auto-min-update-version

Capgo code API metadata SDK --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

、を確認します。「

ネイティブ + OTA フロー

開発/実行チャネル、維持する時期 --fail-on-incompatibleライブアップデートと、意図的にネイティブベースラインを配信する方法

オートオーター (Auto OTA) またはネイティブ (Native)

Wire bundle releaseType GitHub Actions または GitLab に CI が live update vs Capgo を選択するようにする。

バージョン対象

context

Rollbacks

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

ロールバック

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

CLI: バンドル

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

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

ネイティブ互換性を使用している場合 ネイティブ互換性 Capgoのソリューションマーケティングページの「バージョン対象設定」バージョン対象設定ネイティブのバージョンに基づいてバンドルをルーティングするロールバック不互換のバンドルが配信されたときに復元するアップデートの種類 Live Update Capgo CLI バンドル参照 Capacitor