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_KEEP_1__が新しいバンドルに必要な場合、バンドルは: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

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

注意

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__をアップグレードする、ネイティブプロジェクト設定を変更する) は、通常のアプリストア配布プロセスを通じて新しいバイナリビルドを提出する必要があります。

Capgo can send files from your generated web build folder. If the change only affects HTML, CSS, JavaScript, assets, or pure-JavaScript packages bundled into that output, ship it as a live update.

__CAPGO_KEEP_0__ capacitor.config.tsCapacitorのプラグイン設定やネイティブプラグインや依存関係、Capacitor自体、またはiOS/Androidプロジェクトファイルが変更された場合に使用するネイティブアプリのリリースを使用してください。実用的なチェック: npx cap sync __CAPGO_KEEP_0__ npx cap copy 「Change」

「Ship with __CAPGO_KEEP_0__ OTA?」	Ship with Capgo OTA?	「HTML、CSS、アプリケーション用JavaScript、画像、フォント、Webビルドアセットなど」
「Yes」	「Webバンドルからロードされる」	「Pure-JavaScriptパッケージの変更がWeb出力にバンドルされている」
「Yes」	「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のみです 空輸送可能.
• プラグインが追加、削除、またはバージョンが変更された場合、バンドルは ネイティブ非互換 — その変更は、ユーザーが新しいネイティブバイナリをインストールするまで、有効になりません。

Check from the 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 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__CAPGO_KEEP_0__ native.

__CAPGO_KEEP_0__

注意

注意 デフォルトでは不互換性の検出はアップロードをブロックしない — 不互換のネイティブバンドルをアップロードし、そのチャンネルのアクティブビルドとして設定した場合、__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 下記 Prevent incompatible deliveries Prevent incompatible deliveries

On devices still running the older native binary, the missing native __CAPGO_KEEP_0__ 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. __CAPGO_KEEP_0__’s automatic rollback can catch a JavaScript error thrown before runs, but it isn’t a substitute for shipping compatible native __CAPGO_KEEP_0__ — a mismatch that crashes later, or crashes natively, can slip past it., 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 Nativeアプリの変更を安全に配信する方法 Section titled “Nativeアプリの変更を安全に配信する方法” notifyAppReady() バンドルが新しいNative codeが必要な場合、App Store / Play Storeに新しいバイナリを登録し、または__CAPGO_KEEP_1__ Cloud Buildで再構築してください。ユーザーがバイナリを更新すると、バンドルのネイティブ依存関係が整い、ライブアップデートが正しく実行されます。

__CAPGO_KEEP_0__

Native __CAPGO_KEEP_0__

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アップデートを防ぎます: これは、ユーザーがネイティブビルドをインストールするまで効果を発揮しない可能性があるからです セクションのタイトル: 非互換の配信を防ぐ アップロードをCIで失敗させる —

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

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

ネイティブバージョンによるゲート配信 — 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 は では 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を検査することはありません。したがって、メジャーまたはパッチリリースにネイティブの変更が含まれる場合でも、変更は配信されます。

または を使用してください。 ネイティブパッケージを確認します。

詳細なターゲット設定オプションについては

Auto OTA またはネイティブ

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

バージョン対象

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

ロールバック

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

更新タイプ

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

CLI: バンドル

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

ネイティブ互換性から続きます

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