Native Compatibility

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はインストールバイナリにないネイティブ__CAPGO_KEEP_1__を提供できますが、古いネイティブビルドを実行しているデバイスではクラッシュまたは不正動作が発生する可能性があります。

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

注意

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

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

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

__CAPGO_KEEP_0__のネイティブアプリリリースを使用する必要があります。 capacitor.config.tsCapacitorの設定、ネイティブプラグインまたは依存関係、Capacitor自体、またはiOS/Androidプロジェクトファイルの変更が更新される場合に使用します。実用的なチェック: npx cap sync 変更がネイティブプロジェクトを更新する必要がある場合、または npx cap copy インストール済みデバイスで使用できるようにする前に、変更が適用される場合、ネイティブアプリとして扱います。

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

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

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

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

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

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

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

• The ネイティブバイナリ ユーザーはApp Store / Play Storeからインストールします。Capacitor、ネイティブプラグイン、ネイティブ設定が含まれます。
• The JavaScriptバンドル (あなたのウェブアプリケーション)がCapgoでオンエアで更新できる。

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

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

バンドルをアップロードしたり、手動でチェックしたりすると、Capgoは ローカルプロジェクト内のネイティブパッケージ (あなたのCapacitor/Cordovaプラグインとそのバージョン)と、バンドルが現在チャンネルに公開されているネイティブパッケージ を比較します。:

• 互換性がある場合、変更はJavaScriptのみです __CAPGO_KEEP_0__.
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ —

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

__CAPGO_KEEP_0__

追加 --text CIログで便利なので、エモジを入れ替す 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.

What an incompatible update means for your users

注意

デフォルトでは不互換性の検出はアップロードをブロックしません — 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 Prevent incompatible deliveries Prevent incompatible deliveries --fail-on-incompatible Prevent incompatible deliveries Prevent incompatible deliveries Prevent incompatible deliveries

__CAPGO_KEEP_0__の古いネイティブバイナリを実行しているデバイスでは、__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’s セクション: ネイティブ変更を安全に配信する方法 ネイティブ変更を修正するには、実際の修正は新しいネイティブビルドを公開することです 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.

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

セクション:

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

不互換のバンドルがすでにライブ中の場合、戻す

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

不互換の配信を防ぐ

ネイティブパッケージを実際に検査する2つの補完的なガードがあります：

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

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

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

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

ネイティブバージョンによるゲート配信 — metadata + --auto-min-update-version

あなたは nativeビルドとバンドルを一緒に配信する場合、チャンネルを 戦略とアップロードする metadata . __CAPGO_KEEP_0__ は、すべてのアップロードで互換性チェックを実行し、バンドルが新しいネイティブ __CAPGO_KEEP_1__ が必要な場合、更新フロアを上げて、ネイティブビルドをインストールしていないデバイスが受信しないようにします: --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 code を検査することはないため、native の変更がマイナーやパッチリリースで出荷される可能性がある --fail-on-incompatible を使用してください --auto-min-update-versionまたは

, を参照してください バージョン対象設定の詳細は

関連

バージョン対象

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

ロールバック

不互換のバンドルが配信された場合に、最後の互換性のあるビルドにチャンネルを戻します。

アップデートタイプ

適用タイミング、遅延条件、バージョンブロックがどのように組み合わさるかを説明します。

CLI: バンドル

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

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

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