ネイティブ互換性

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.

です: __CAPGO_KEEP_0__はそれでも配信できますが、古いネイティブビルドが実行されているデバイスではクラッシュまたは不正動作が発生する可能性があります。

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.

注意:注意:ライブアップデートはJavaScriptバンドル変更に限定されています。ネイティブ__CAPGO_KEEP_0__を更新する必要がある場合（プラグインの追加または削除、__CAPGO_KEEP_1__のアップグレード、ネイティブプロジェクト設定の変更）には、通常のアプリストア配信プロセスを通じて新しいバイナリビルドを提出する必要があります。TLDR: OTAまたはネイティブ?

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

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

ネイティブアプリリリースを使用する必要があります。	Ship with Capgo OTA?	ライブアップデートとして __CAPGO_KEEP_0__ を送信しますか?
なぜ	HTML、CSS、アプリケーションの JavaScript、画像、フォント、他のウェブビルド資産	はい
Pure-JavaScript パッケージの変更が、Web 出力にバンドルされます。	はい	生成された JavaScript は Web バンドルの一部です。
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層で配布されます:

• 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 CIログで便利なemojiを入れ替え、モノレポで正しいパスを指す OK/FAIL CIで機械読み取り可能な判定を取得する --package-json / --node-modules CIで機械読み取り可能な判定を取得する

パイプラインの場合、チェックを単一のワードに縮小します:

クリップボードにコピー bundle releaseType CIログで便利なemojiを入れ替え、モノレポで正しいパスを指す

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 はそれを デバイスに配信する --fail-on-incompatible それをハードゲートに変えることができる — 以下を参照 不互換の配信を防止する 以下の説明を参照してください。

まだ古いネイティブバイナリを実行しているデバイスでは 古いネイティブバイナリを実行しているデバイスでは, これにより、更新がダウンロードされ適用されたにもかかわらず、クラッシュや機能が破損する原因となる code が欠如する可能性があります。 これが、ライブアップデートがライブで配信されていても、既存のユーザーにとってアプリが破損する原因となるのはなぜか、そして Capgo が不互換のバンドルがライブになる際に警告を出すのはなぜかという理由です。

Capgo の 自動的なロールバック 実行される前に投げられた JavaScript エラーをキャッチできますが、それはネイティブの __CAPGO_KEEP_0__ が互換性のあるものであることを保証するための代替手段ではありません。 それでも、後でクラッシュする、またはネイティブでクラッシュする、不互換の __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__で失敗し、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-versionでアップロードします。 Capgo はアップロードごとに互換性チェックを実行し、バンドルが新しいネイティブ 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 は ない 代替品ではありません — ただし、バージョンジャンプのみをブロックし、ネイティブコードを検査することはありません code, したがって、ミニマムまたはパッチリリースでネイティブ変更が含まれる場合でも、ネイティブ変更は配信されます。 --fail-on-incompatible または --auto-min-update-versionCapacitorライブアップデートの代替品を使用する場合、

バージョンをチェックする Capacitor バージョン対象設定

すべての対象設定を参照してください。

関連

ネイティブ+OTAワークフロー --fail-on-incompatible開発/運用チャネル、変更を保持するとき、そして意図的にネイティブベースラインを配信する方法

オート OTA またはネイティブ

Wire bundle releaseType GitHub アクションまたは GitLab に入力して、CI がライブ更新を検出するか Capgo ビルドを検出するかを判断するようにします。

バージョン対象

ページ/エリア: Capgo ソリューションズ マーケティング ページ。役割: セクションまたはページ ヘッダー。見られる場所: page solutions/version-targeting.astro。メッセージ キー `solutions_version_targeting_title` (ソリューションズ バージョン対象タイトル)。| ページ/エリア: Capgo ソリューションズ マーケティング ページ。役割: 短い UI ラベルまたはナビゲーション アイテム。見られる場所: page solutions/version-targeting.astro。メッセージ キー `solutions_version_targeting` (ソリューションズ バージョン対象)。

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

ロールバック

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

アップデート タイプ

CLI: bundle

__CAPGO_KEEP_0__: バンドル

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

あなたは Native Compatibility Native Compatibilityを安全に保つために使用している場合 バージョン対象設定 コンテキスト: Capgoのソリューションマーケティングページ。役割: セクションまたはページヘッダー。見られる場所: page solutions/version-targeting.astro。メッセージキー `solutions_version_targeting_title` (ソリューション バージョン対象設定タイトル)。 | コンテキスト: Capgoのソリューションマーケティングページ。役割: 短いUIラベルまたはナビゲーションアイテム。見られる場所: page solutions/version-targeting.astro。メッセージキー `solutions_version_targeting` (ソリューション バージョン対象設定)。 バンドルをネイティブバージョンにルーティングする ロールバック 不互換のバンドルが配信されたときに復元する アップデートの種類 Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ バンドル参照