Native Kompatibilität

A Capgo Live-Update ersetzt Ihren App-Bundle sofort, aber es kann die native App-Teile nicht ändern — die Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfiguration, die in der installierten Binärdatei kompiliert wurden. Wenn ein neuer Bundle native __CAPGO_KEEP_1__ erwartet, die die installierte Binärdatei nicht hat, ist der Bundle inkompatibel. JavaScript-Bundle unverändert native 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__ kann es immer noch liefern, aber es kann auf Geräten, die noch die ältere native Build laufen, abstürzen oder 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 liefern können.

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

Live-Updates sind auf JavaScript-Bundle-Änderungen beschränkt. Wenn Sie native __CAPGO_KEEP_0__ aktualisieren müssen — ein Plugin hinzufügen oder entfernen, __CAPGO_KEEP_1__ upgraden oder die native Projekt-Konfiguration ändern — müssen Sie ein neues Binär-Update über die übliche App-Store-Distribution-Prozess einreichen.

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.

__CAPGO_KEEP_0__ ist ein Brandname, der nicht übersetzt werden sollte. __CAPGO_KEEP_1__ ist ein Brandname, der nicht übersetzt werden sollte.

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änkt, senden Sie es als Live-Update.

Verwenden Sie eine native App-Veröffentlichung, wenn sich der Änderung auf capacitor.config.ts, die Plugin-Konfiguration in Capacitor-Konfiguration, native Plugins oder Abhängigkeiten, Capacitor selbst oder iOS/Android-Projektdateien bezieht. Eine praktische Überprüfung: Wenn sich der Änderung auf das native Projekt durch npx cap sync oder npx cap copy context

oder	Ship with Capgo OTA?	oder
context	oder	context
JavaScript-Paketänderungen, die in Ihrem Weboutput gebündelt werden	Ja	Das generierte JavaScript ist Teil des Webbundles.
capacitor.config.ts Änderungen	Nein	Capacitor-Konfiguration wird bei der Buildzeit in die native App gelesen.
Hinzufügen, Entfernen oder Upgraden von Capacitor/Cordova-Plugins	Nein	Die installierte native Binärdatei muss die passende native code enthalten.
Änderungen an iOS- oder Android-Projektdateien	Nein	Bestehende Benutzer benötigen eine neue Binärdatei aus den Stores.

Kundenplugins nach Stapel

Capgo stellt für jeden hybriden Laufzeitumgebung einen dedizierten Updater-Client bereit:

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

Die nativen Kompatibilitätsprüfungen gelten unabhängig vom Kundenplugin – sie vergleichen die im Bundle aufgezeichneten nativen Abhängigkeiten mit der installierten Binärdatei.

Weshalb nativer Kompatibilität wichtig ist

Jede Capacitor-Anwendung wird in zwei Schichten geliefert:

• Die die native binäre Benutzer installieren sie von der App Store / Play Store. Sie enthält Capacitor, Ihre native Plugins und die native Konfiguration.
• Die JavaScript-Bundle (Ihre Webanwendung) das Capgo über drahtlose Aktualisierungen aktualisieren kann.

Eine lebende Aktualisierung ersetzt nur die JavaScript-Schicht. Wenn das neue JavaScript eine native Funktion oder API aufruft, die nicht in der installierten Binärdatei kompiliert wurde, schlägt die Aufrufung bei der Ausführung fehl – was das Programm zum Absturz bringen oder stillschweigend eine Funktion brechen kann. Kurz gesagt: Capgo kann die native code nicht aktualisieren, daher 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 die Kompatibilität erkennt

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

• Wenn sie übereinstimmen, ist die Änderung nur JavaScript-basiert und sicher zum Übertrag über die Luft.
• Wenn ein Plugin hinzugefügt, entfernt oder auf eine neue Version aktualisiert wurde, ist das Bundle native-inkompatibel — 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 mit jedem native Paket mit seiner lokalen Version, der Version im 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

Tip

Hinzufügen --text um die Emojis auszutauschen (händisch in CI-Protokollen) und OK/FAIL um auf die richtigen Pfade in einem monorepos-Verzeichnis zu zeigen. --package-json / --node-modules Erhalten Sie eine maschinenlesbare Verurteilung (CI)

Abschnitt mit dem Titel “Erhalten Sie eine maschinenlesbare Verurteilung (CI)”

reduziert die Überprüfung auf ein einzelnes Wort: bundle releaseType Terminalfenster

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 Ihren Release-Pipeline auf dieser Basis: Verschicken Sie ein Live-Update, wenn es druckt OTAund lösen Sie eine native Build aus, wenn es druckt native.

Wie eine inkompatible Aktualisierung für Ihre Benutzer bedeutet

Vorsicht

Standardmäßig wird die Inkompatibilität nicht detektiert die Upload-Blockierung — wenn Sie ein native-inkompatibles Bundle hochladen und es als aktives Build eines Kanals setzen, Capgo werden es den Geräten auf diesem Kanal liefern (Sie können dies in eine harte Schranke umwandeln, --fail-on-incompatible — siehe Verhindere inkompatible Lieferungen unten.)

Bei Geräten, die noch immer die ältere native Binärdatei laufen lassen die fehlende native __CAPGO_KEEP_0__ kann zu Crashes oder gebrochenen Funktionen führen — auch wenn die Aktualisierung heruntergeladen und angewendet wurde „erfolgreich“. Dies ist der Grund, warum eine Live-Update live und geliefert werden kann, aber trotzdem für bestehende Benutzer den App-Betrieb stören kann, und warum __CAPGO_KEEP_1__ Sie warnen kann, wenn ein inkompatibles Bundle live geht., 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 eine JavaScript-Fehlermeldung werfen kann, bevor läuft, aber es ist kein Ersatz für die Bereitstellung von kompatiblen native __CAPGO_KEEP_0__ — ein Mismatch, der später abstürzt oder natively abstürzt, kann es umgehen. 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 „Wie Sie native Änderungen sicher bereitstellen können“

Publish a new native build (the real fix)

Wenn ein Bundle neue natives code benötigt, erstellen und submiten Sie ein neues Binär auf dem App Store / Play Store (oder rebuilden Sie es mit Capgo Cloud Build). Sobald die Benutzer das Binär aktualisieren, passen sich die natives Abhängigkeiten des Bundles an und der Live-Update läuft richtig.

Zurücksetzen, wenn ein inkompatibles Bundle bereits live ist

Wenn ein inkompatibles Bundle bereits auf einem Kanal aktiv ist, setzen Sie den Kanal auf die letzte kompatible Build zurück, um es bis zum Erscheinen des natives Builds auszuschenken. Siehe Rücksetzungen.

Unvereinbare Lieferungen verhindern

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

Die Upload-Verarbeitung in CI – --fail-on-incompatible

Hinzufügen Sie die Flagge zu Ihrem bundle upload Schritt. Wenn die natives Pakete des Bundles nicht mit der derzeit liveen Version des Kanals übereinstimmen, wird der Upload Fehlschlägt mit einer Nicht-Null-Ausgabenummer und wird nichts verschickt. — also wird deine Pipeline verhindern, dass du stillschweigend eine OTA-Update veröffentlicht, das erst dann wirksam wird, wenn die Benutzer eine native Anwendung installieren:

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

Kompatible Uploads — und Fälle, in denen der Check nicht ausgeführt werden kann (ein neuer Kanal oder keine Remote-Metadaten) — werden unverändert weitergeleitet. In einem interaktiven Terminal bietet es stattdessen den Capgo-Builder-Flow für native Builds an; Ablehnung schlägt fehl. (Kann nicht mit --ignore-metadata-check.)

Tip

Wenn du vorsätzlich brauchst, dass ein Bundle von den im Kanal lebenden native Paketen abweicht (neuer Plugin, Capacitor-Upgrade und so weiter), lasse den --fail-on-incompatible damit für die Basis-Uploads. Halte die Flagge auf jedem alltäglichen OTA- CI. Vollständiger Kanal-Workflow: Native + OTA-Kanal-Workflow.

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

Wenn Sie machen den native Build und das Bundle gemeinsam verschicken, legen Sie den Kanal auf die metadata Strategie und laden Sie mit --auto-min-update-version. Capgo führt die Kompatibilitätsprüfung bei jedem Upload durch und hebt bei einem Bundle, das neue native code benötigt, die Aktualisierungsstufe an, so dass Geräte, die das entsprechende native Build noch nicht installiert haben, es nicht erhalten:

# 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

Vorsicht

Versionenregeln wie --disable-auto-update major gelten nicht kein Ersatz — sie blockieren nur Sprungversionen und untersuchen nie native code, daher geht ein native Änderung, die in einer Minor- oder Patchversion verschickt wird, immer raus. Verwenden Sie --fail-on-incompatible oder --auto-min-update-versionVersionziel

zur vollständigen Zielgruppenauswahl zugehörig Abteilung: Native + OTA Workflow

Entwicklungs- und Produktionskanäle, wann man sie behalten sollte

und wie man eine absichtliche native Basis versendet

und wie man eine absichtliche native Basis versendet --fail-on-incompatibleund wie man eine absichtliche native Basis versendet

Auto OTA oder Native

Wire bundle releaseType into GitHub Actions or GitLab so CI picks live update vs Capgo Build.

Versionziel

Erstelle nur kompatible Pakete mit Kanälen, semver-Regeln und der Metadatenstrategie.

Rückgänge

Rückgänge auf einen vorherigen kompatiblen Build durchführen, wenn ein inkompatibles Paket live ging.

Update-Typen

Erkläre, wie Anwendungszeitpunkt, Verzögerungsbedingungen und Versionsblockierung zusammenarbeiten.

CLI: Paket

Referenz für die Paket-Kompatibilität, releaseType und Upload-Optionen.

Fortsetzung von Native-Kompatibilität

Wenn Sie Native Kompatibilität verwenden Native Kompatibilität um Live-Updates sicher zu halten, verbinden Sie es mit Version-Zielsetzung um Bundles nach nativer Version zu routen, Rückgänge um wiederherzustellen, wenn ein inkompatibler Bundle abgesendet wird, Update-Typen um das Kanalversion-Blockieren zu verstehen, und die Capgo CLI Bundle-Referenz zur Kompatibilität und releaseType-Befehle.