ネイティブ互換性

Capgo ライブアップデートは、 Capgo アプリのJavaScriptバンドルを即時置き換えますが、 Capgo/Cordovaプラグイン、ネイティブ依存関係、ネイティブプロジェクト構成がコンパイルされたインストール済みバイナリに含まれているため、ネイティブの部分は置き換えられません。新しいバンドルがインストール済みバイナリにないネイティブ __CAPGO_KEEP_1__ を期待している場合、バンドルはネイティブ非互換となります。 __CAPGO_KEEP_0__ は、インストール済みバイナリが持っていないネイティブ __CAPGO_KEEP_1__ を提供できますが、古いネイティブビルドを実行しているデバイスではクラッシュまたは不正動作が発生する可能性があります。 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 がネイティブ互換性を検出する方法、ユーザーに不互換の更新が何を意味するか、ネイティブの変更を安全に配信する方法について説明しています。

注意

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

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

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

• 「 ユーザーがApp Store / Play Storeからインストールするネイティブバイナリです。__CAPGO_KEEP_0__、ネイティブプラグイン、およびネイティブ構成が含まれます。 users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• JavaScript バンドル JavaScript bundle (あなたのウェブアプリ) が Capgo でオンデマンドで更新できるようにする。

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

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

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

• と比較します 一致すると、変更はJavaScriptのみで.
• オンデマンドで安全に配信できます プラグインが追加、削除、またはバージョンが変更された場合、bundleはnative-incompatibleです — ユーザーが新しいネイティブバイナリをインストールした後のみに有効になる変更はすべて。

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__はそのチャンネルのデバイスに配信される。 (これをハードゲートに変えることができる — 以下の「不互換配信を防止する」で参照。) 古いnativeバイナリを実行しているデバイスでは、欠落しているnative __CAPGO_KEEP_0__がクラッシュや機能の破損を引き起こす可能性がある — それでもアップデートがダウンロードされ「成功」に適用された。 これは、ライブアップデートがライブで配信されても既存のユーザーにとってアプリを破損させることができるため、__CAPGO_KEEP_1__は不互換のバンドルがライブになったときに警告を出すことができる。 Capgo __CAPGO_KEEP_1__ __CAPGO_KEEP_0__ --fail-on-incompatible __CAPGO_KEEP_1__ Prevent incompatible deliveries Prevent incompatible deliveries

Prevent incompatible deliveries Prevent incompatible deliveries, 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エラーだけです notifyAppReady() 実行される前に投げられたJavaScriptエラーだけをキャッチできるので、互換性のないネイティブcodeを配布することはできません。実行時には、またはネイティブでクラッシュする可能性がある、後でクラッシュする可能性のある不一致は、自動ロールバックでは検出されません。

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

実際の修正は、Publish a new native build (the real fix) です。

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

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

See ロールバック.

不互換の配信を防止する

両方の補完的なガード、実際にはネイティブパッケージを検査します:

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

ネイティブ版の配信 — metadata + --auto-min-update-version

あなたが 実行する ネイティブ版のビルドとバンドルを一緒に配信する場合、チャネルを戦略に設定し、__CAPGO_KEEP_0__でアップロードする。 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 protectedTokens __CAPGO_KEEP_0__は代替ではありません — これらはバージョンジャンプのみをブロックし、ネイティブの__CAPGO_KEEP_0__を検査することはありません。したがって、メジャーまたはパッチリリースでネイティブの変更が含まれる場合でも、ネイティブの変更は配信されます。 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、を使用して、ネイティブのパッケージを確認します。

See バージョン対象設定の詳細は、 Version Targeting

を参照してください。

関連

Version Targeting

バージョン対象設定を使用して、互換性のあるバンドルを配信することができます。チャンネル、semver規則、メタデータ戦略を使用して、配信を制御します。

__CAPGO_KEEP_0__: bundle

Update Types

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

CLI: bundle

Reference for the bundle compatibility, releaseType, and upload options.

Keep going from Native Compatibility

If you are using Native Compatibility to keep live updates safe, connect it with Version Targeting to route bundles by native version, ロールバック 不互換のバンドルが配信されたときに復元する 更新タイプ チャンネルバージョンブロッキングを理解し、 Capgo CLI バンドル参照 互換性とリリースタイプのコマンドのために。