Native Compatibility

Ein Capgo Live-Update ersetzt die JavaScript-Bundle Ihres Apps. Ein __CAPGO_KEEP_0__ live update ersetzt die JavaScript-Bundle Ihrer App. unmittelbar, aber es kann die eigene Teil Ihrer App — die Capacitor/Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfiguration, die in die installierte Binärdatei kompiliert werden. Wenn ein neuer Bundle native code erwartet, die die installierte Binärdatei nicht hat, ist der Bundle native-inkompatibel: Capgo kann es immer noch liefern, aber es kann auf Geräten, die noch die ältere native Build ausführen, abstürzen oder sich falsch verhalten.

Dieses Dokument erklärt, wie Capgo native Kompatibilität erkennt, was eine inkompatible Aktualisierung für Ihre Benutzer bedeutet und wie Sie native Änderungen sicher verschicken können.

Hinweis

Live-Updates sind auf Änderungen an JavaScript-Bundles beschränkt. Wenn Sie native code — indem Sie ein Plugin hinzufügen oder entfernen, Capacitor upgraden oder die native Projekt-Konfiguration ändern — aktualisieren müssen, müssen Sie ein neues Binärbuild über die übliche App-Store-Verteilungsprozess einreichen.

TLDR: OTA oder native?

Capgo kann Dateien aus Ihrem generierten Web-Build-Ordner senden. Wenn sich der Änderung nur auf HTML, CSS, JavaScript, Assets oder reinen JavaScript-Pakete, die in diesem Output gebündelt sind, beschränken, senden Sie es als Live-Update.

Verwenden Sie eine native App-Version, wenn eine Änderung aktualisiert capacitor.config.ts, die Plugin-Konfiguration wird in Capacitor Konfiguration, native Plugins oder Abhängigkeiten, Capacitor selbst oder iOS/Android-Projektdateien gespeichert. Eine praktische Überprüfung: Wenn die Änderung die native Projektdatei aktualisieren muss, bevor installierte Geräte sie verwenden können, behandeln Sie sie als native. npx cap sync Change npx cap copy Mit __CAPGO_KEEP_0__ OTA liefern?

Warum	Ship with Capgo OTA?	Ja
Sie werden zur Laufzeit aus dem Web-Bundle geladen.	Reine-JavaScript-Paket-Änderungen, die in Ihr Web-Ausgabe gebündelt sind	Ja
Sie werden zur Laufzeit aus dem Web-Bundle geladen.	Reine-JavaScript-Paket-Änderungen, die in Ihr Web-Ausgabe gebündelt sind	The generierte JavaScript ist Teil des Web-Bundles.
capacitor.config.ts Änderungen	Nein	Capacitor-Konfiguration wird bei der Zeit des Builds in die native App gelesen.
Hinzufügen, entfernen oder Capacitor/Cordova-Plugins aktualisieren	Nein	Die installierte native Binärdatei muss die passende native code enthalten.
Änderungen in iOS- oder Android-Projektdateien	Nein	Bestehende Benutzer benötigen eine neue Binärdatei aus den Stores.

Client-Plugins nach Stack

Capgo stellt dedizierte Updater-Klienten für jeden hybriden Laufzeitumgebung bereit:

Plugin	Verwenden Sie, wenn
@capgo/capacitor-updater	Capacitor-iOS/Android-Anwendungen
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ Anwendungen
@capgo/electron-updater	Elektron-Desktop-Anwendungen

Nativkompatibilitätsprüfungen gelten unabhängig vom Client-Plugin – sie vergleichen die im Bundle aufgezeichneten nativen Abhängigkeiten mit den installierten Binärdateien.

Warum Nativkompatibilität wichtig ist

Jedes Capacitor-Programm wird in zwei Schichten geliefert:

• Der nativ binäre Benutzer installieren es aus dem App Store / Play Store. Es enthält Capacitor, Ihre native Plugins und native Konfiguration.
• Die JavaScript-Bundle (Ihre Webanwendung) das Capgo über die Luft aktualisieren kann.

Ein Live-Update ersetzt nur die JavaScript-Schicht. Wenn das neue JavaScript eine native Plugin oder API aufruft, das nicht in der installierten Binärdatei kompiliert wurde, schlägt die Aufruf bei der Ausführung fehl – was das Programm zum Absturz bringen oder stillschweigend eine Funktion brechen kann. Kurz gesagt: Capgo kann native code nicht aktualisieren, also kann ein Gerät, das die alte native Version läuft, nicht sicher eine Bundle ausführen, die gegen neue native code erstellt wurde.

Wie Capgo Kompatibilität erkennt

Wenn Sie ein Bundle hochladen – oder die Überprüfung manuell durchführen – vergleicht Capgo die native Packages im lokalen Projekt (Ihre Capacitor/Cordova-Plugins und ihre Versionen) mit den native Packages, die für das Bundle aktuell im Kanal:

• registriert sind. Wenn sie übereinstimmen, ist die Änderung nur JavaScript-basiert und sicher zum Luftübertrag über die Luft zu senden.
• Wenn ein Plugin hinzugefügt, entfernt oder eine Versionsänderung vorgenommen wurde, ist das Bundle nicht kompatibel mit der nativen Plattform — diese Änderungen wirken sich erst dann aus, wenn die Benutzer eine neue native Binärdatei installieren.

Überprüfen Sie von der CLI

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

Die CLI druckt eine Tabelle für jedes native Paket mit seiner lokalen Version, der Version live auf dem Kanal und einem Status:

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

Tipp

Hinzufügen --text um die Emojis auszutauschen für OK/FAIL (nützlich in CI-Protokollen), und --package-json / --node-modules um auf die richtigen Pfade in einem monorepos-Verzeichnis zu zeigen.

Erlangen Sie eine maschinenlesbare Verdict (CI)

Für Pipelines bundle releaseType verkleinert die Überprüfung in ein einzelnes Wort:

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

Blockieren Sie Ihre Releasepipeline auf dieser: Verschicken Sie ein Live-Update, wenn es druckt OTA, und lösen Sie ein natives Build aus, wenn es druckt native.

Was bedeutet ein inkompatibles Update für Ihre Benutzer

Vorsicht

Standardmäßig wird die Inkompatibilität erkannt, aber die Upload-Verarbeitung nicht blockiert — wenn Sie ein natives-in-kompatibles Bundle hochladen und es als aktives Build für einen Kanal festlegen, __CAPGO_KEEP_0__ wird es 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

On Geräten, die noch das ältere native Binärdatei verwenden, kann das fehlende native __CAPGO_KEEP_0__ zu Crashes oder gebrochenen Funktionen führen — obwohl die Aktualisierung heruntergeladen und angewendet wurde „erfolgreich“. Dies ist der Grund, warum eine Live-Update live und geliefert werden kann, aber dennoch den App für bestehende Benutzer brechen kann, und warum __CAPGO_KEEP_1__ Sie warnen kann, wenn ein inkompatibles Bundle live geht. __CAPGO_KEEP_0__’s, 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.

keine Ersatz für die Bereitstellung von kompatiblen native Capgo — ein Mismatch, das später abstürzt oder natively abstürzt, kann es umgehen. Wie man native Änderungen sicher bereitstellt Abschnitt mit dem Titel „Wie man native Änderungen sicher bereitstellt“ 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.

Abschnitt mit dem Titel „Einen neuen native Build veröffentlichen (die wahre Lösung)“

Section titled

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.

Wenn ein inkompatibles Bundle bereits live ist, rückgängig machen

Wenn ein inkompatibles Bundle bereits auf einem Kanal aktiv ist, kehren Sie den Kanal zur letzten kompatiblen Version zurück, um es bis zum Erscheinen des nativen Builds nicht zu liefern. Siehe Rückgänge.

Verhindere inkompatible Lieferungen

Zwei komplementäre Wächter, die beide tatsächlich Ihre native Pakete überprüfen:

Führen Sie die Upload-Verarbeitung in CI ab — --fail-on-incompatible

Fügen Sie die Flagge Ihrem bundle upload Schritt. Wenn die Pakete des Bundles nicht mit der derzeit liveen Version des Kanals übereinstimmen, scheitert der Upload mit einer nicht Nullen-Zahl und wird nichts geliefert — so stoppt Ihre Pipeline Sie daran, ein OTA-Update stillschweigend zu veröffentlichen, das erst dann wirksam werden kann, wenn die Benutzer ein natives Build installieren:

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

Kompatible Uploads — und Fälle, in denen die Überprüfung nicht durchgeführt werden kann (ein neuer Kanal oder keine Remote-Metadaten) — werden unverändert weitergeleitet. In einem interaktiven Terminal bietet es den Capgo-Builder die native-Build-Flow an; Ablehnung führt zum Scheitern. (Kann nicht mit --ignore-metadata-check.)

Lieferung durch native Version — metadata + --auto-min-update-version

Wenn Sie den native Build und das Bundle gemeinsam versenden, legen Sie den Kanal auf die Strategie und laden Sie mit metadata . __CAPGO_KEEP_0__ führt die Kompatibilitätsprüfung auf jedem Upload durch und, wenn ein Bundle neue native __CAPGO_KEEP_1__ benötigt, hebt es den Update-Fußboden an, damit Geräte, die das entsprechende native Build noch nicht installiert haben, es nicht erhalten: --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

Achtung

Versionierungsregeln wie --disable-auto-update major sind kein Ersatz — sie blockieren nur Versionssprünge und überprüfen keine native code, also geht ein native Änderung, die in einem Minor- oder Patch-Release verschickt wird, immer raus. Verwenden --fail-on-incompatible oder --auto-min-update-version, die Ihre native Pakete überprüfen.

Siehe Version-Zielsetzung für die vollständige Liste der Zielsetzungsoptionen.

Zugehörige

Zielgruppenspezifische Versionen

Liefere nur kompatible Pakete mithilfe von Kanälen, semver-Regeln und der Metadatenstrategie.

Rückgänge

Rückgängig machen Sie einen Kanal auf die letzte kompatible Version, wenn ein inkompatibles Paket live ging.

Update-Typen

Erklären Sie, wie die Verzögerung, die Verzögerungsbedingungen und die Versionsblockierung zusammenarbeiten.

CLI: Paket

Referenz für die Paketkompatibilität, releaseType und Uploadoptionen.

Weitermachen von Native Kompatibilität

Native Kompatibilität Wenn Sie Native Kompatibilität verwenden um lebendige Updates sicher zu halten, verbinden Sie es mit Zielversion um Bundle durch native Version zu routen, Rückgänge um wiederherzustellen, wenn ein inkompatibles Bundle abgesendet wird, Update-Typen um den Kanalversionen zu verstehen, die Blockierung und den Capgo CLI Bundle-Referenz für die Kompatibilität und die releaseType-Befehle.