Native-Kompatibilität

Ein Capgo live update ersetzt sofort das JavaScript-Bundle Ihrer App, kann aber nicht den nativ Teil Ihrer App ändern – die Capacitor/Cordova-Plugins, nativen Abhängigkeiten und die native Projektkonfiguration, die in die installierte Binärdatei kompiliert wurden. Wenn ein neues Bundle native code erwartet, die die installierte Binärdatei nicht besitzt, wird das Bundle native-inkompatibel: Capgo kann es zwar ausliefern, aber es kann auf Geräten mit einem älteren Native Build abstürzen oder Fehlfunktionen aufweisen.

Diese Seite erklärt, wie Capgo die native Kompatibilität erkennt, was ein inkompatibles Update für deine Nutzer bedeutet und wie du native Änderungen sicher veröffentlichst.

Hinweis

Live Updates sind auf Änderungen am JavaScript-Bundle beschränkt. Wenn du native code aktualisieren musst – etwa durch das Hinzufügen oder Entfernen eines Plugins, das Upgrade von Capacitor oder Änderungen an der nativen Projektkonfiguration – musst du einen neuen Binary Build über den üblichen App-Store-Prozess einreichen.

TLDR: OTA oder native?

Capgo kann Dateien aus deinem generierten Web-Build-Ordner senden. Wenn sich die Änderung nur auf HTML, CSS, JavaScript, Assets oder reine JavaScript-Packages auswirkt, die in diesen Output gebündelt sind, liefere sie als live update aus.

Nutze ein Native Build, wenn eine Änderung... capacitor.config.ts, in der Capacitor-Config gespeicherte Plugin-Konfiguration, native Plugins oder Dependencies, Capacitor selbst oder iOS-/Android-Projektdateien. Ein praktischer Check: Wenn die Änderung das native Projekt über npx cap sync oder npx cap copy Behandle es als native, bevor installierte Geräte es nutzen können.

Änderung	Mit Capgo OTA ausliefern?	Warum
HTML, CSS, App-JavaScript, Bilder, Fonts und andere Web-Build-Assets	Ja	Diese werden zur Laufzeit aus dem Web-Bundle geladen.
Änderungen an reinen JavaScript-Packages, die in deinen Web-Output gebündelt werden	Ja	Das generierte JavaScript ist Teil des Web-Bundles.
capacitor.config.ts Änderungen	Nein	Die Capacitor-Konfiguration wird beim Build in die native App eingelesen.
Hinzufügen, Entfernen oder Upgraden von Capacitor/Cordova-Plugins	Nein	Die installierte native Binary muss das passende native code enthalten.
Änderungen an iOS- oder Android-Projektdateien	Nein	Bestehende Nutzer benötigen eine neue Binary aus den Stores.

Client-Plugins nach Stack

Capgo liefert dedizierte Updater-Clients für jede Hybrid-Runtime:

Plugin	Anwendungsfall
@capgo/capacitor-updater	Capacitor iOS/Android Apps
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ Apps
@capgo/electron-updater	Electron Desktop-Apps

Native Kompatibilitätsprüfungen erfolgen unabhängig vom Client-Plugin – sie vergleichen die im Bundle registrierten nativen Abhängigkeiten mit der installierten Binary.

Warum native Kompatibilität wichtig ist

Jede Capacitor App besteht aus zwei Schichten:

• Der native Binary Nutzer installieren sie über den App Store / Play Store. Sie enthält Capacitor, deine nativen Plugins und die native Konfiguration.
• Der JavaScript-Bundle (deine Web-App), die Capgo over-the-air aktualisieren kann.

Ein live update tauscht nur den JavaScript-Layer aus. Wenn dieses neue JavaScript ein natives Plugin oder API aufruft, das nicht in der installierten Binary kompiliert wurde, schlägt der Aufruf zur Laufzeit fehl – was die App zum Absturz bringen oder Features lautlos unbrauchbar machen kann. Kurz gesagt: Capgo kann natives code nicht aktualisieren. Ein Gerät mit dem alten Native Build kann daher kein Bundle sicher ausführen, das gegen ein neues natives code gebaut wurde.

Wie Capgo Kompatibilität erkennt

Wenn du ein Bundle hochlädst – oder den Check manuell ausführst – vergleicht Capgo die nativen Packages in deinem lokalen Projekt (deine Capacitor/Cordova Plugins und deren Versionen) mit den nativen Packages, die für das Bundle aktuell im Channel live sind:

• Wenn sie übereinstimmen, ist die Änderung rein JavaScript-basiert und sicher per Over-the-Air zu deployen.
• Falls ein Plugin hinzugefügt, entfernt oder die Version geändert wurde, ist das Bundle native-inkompatibel — diese Änderungen werden erst wirksam, wenn Nutzer ein neues Native Build installieren.

Prüfung über CLI

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

Die CLI gibt eine Tabelle aller nativen Pakete mit der lokalen Version, der Version im Channel und dem Status aus:

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

Füge --text um die Emojis zu ersetzen durch OK/FAIL (praktisch in CI-Logs), und --package-json / --node-modules um im Monorepo auf die richtigen Pfade zu verweisen.

Maschinenlesbares Ergebnis erhalten (CI)

Für Pipelines: bundle releaseType fasst die Prüfung in einem einzigen Wort zusammen:

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

Nutze dies als Gate für deine Release-Pipeline: Versende ein live update, wenn ausgegeben wird OTA, und starte einen Native Build, wenn ausgegeben wird native.

Was inkompatible Updates für User bedeuten

Achtung

Standardmäßig blockiert die Erkennung von Inkompatibilitäten es nicht den Upload — wenn du ein native-inkompatibles Bundle hochlädst und es als aktiven Build eines Channels festlegst, Capgo wird es ausliefern an die Geräte in diesem Channel aus. (Du kannst daraus ein Hard Gate machen --fail-on-incompatible — siehe Inkompatible Deployments verhindern unten.)

Auf Geräten, die noch die ältere native Binary ausführen, kann das fehlende native code zu Abstürzen oder defekten Features führen — obwohl das Update „erfolgreich“ heruntergeladen und angewendet wurde. Das ist der Grund, warum ein live update live sein und ausgeliefert werden kann und trotzdem die App für bestehende Nutzer kaputt macht, und warum Capgo dich warnen kann, wenn ein inkompatibles Bundle live geht.

Capgos automatischem Rollback kann JavaScript-Fehler abfangen, die vor notifyAppReady() der Ausführung auftreten, ist aber kein Ersatz für kompatible native code — ein Mismatch, der später zu Abstürzen führt oder direkt nativ crasht, kann so unentdeckt bleiben.

Native Änderungen sicher ausrollen

Neuen Native Build veröffentlichen (der eigentliche Fix)

Wenn ein Bundle neue native code benötigt, erstelle und reiche eine neue Binary im App Store / Play Store ein (oder nutze Capgo Cloud Build). Sobald die Nutzer die Binary aktualisiert haben, passen die nativen Abhängigkeiten des Bundles und live update läuft korrekt.

Rollback, wenn ein inkompatibles Bundle bereits live ist

Falls ein inkompatibles Bundle bereits auf einem Channel aktiv ist, setze den Channel auf den letzten kompatiblen Build zurück, um die Auslieferung zu stoppen, bis der Native Build verfügbar ist. Siehe Rollbacks.

Inkompatible Deployments verhindern

Zwei ergänzende Schutzmechanismen, die deine nativen Packages prüfen:

CI-Upload fehlschlagen lassen — --fail-on-incompatible

Füge das Flag zu deinem bundle upload Schritt. Wenn die nativen Pakete des Bundles nicht mit der aktuell Live-Version des Channels übereinstimmen, wird der Upload mit einem Exit-Code ungleich Null fehl und es wird nichts veröffentlicht — so verhindert deine Pipeline, dass du stillschweigend ein OTA-Update veröffentlichst, das erst nach einem Native Build wirksam wird:

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

Kompatible Uploads — sowie Fälle, in denen der Check nicht laufen kann (neuer Channel oder keine Remote-Metadaten) — gehen unverändert durch. In einem interaktiven Terminal wird stattdessen der Capgo Builder native-build Flow angeboten; eine Ablehnung führt zum Abbruch. (Kann nicht kombiniert werden mit --ignore-metadata-check.)

Tipp

Wenn du absichtlich ein Bundle benötigst, das von den Live-Native-Packages des Channels abweicht (neues Plugin, Capacitor Upgrade usw.), lass --fail-on-incompatible für diesen Baseline-Upload weg. Behalte das Flag in deiner täglichen OTA CI bei. Voller Channel-Workflow: Native + OTA Channel Workflow.

Auslieferung nach Native-Version steuern — metadata + --auto-min-update-version

Wenn du versende den Native Build und das Bundle zusammen, setze den Channel auf die metadata Strategie und lade mit hoch --auto-min-update-version. Capgo führt bei jedem Upload einen Kompatibilitätscheck durch. Wenn ein Bundle neue native code benötigt, wird die Update-Untergrenze angehoben, damit Geräte ohne das passende Native Build das Update 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

Achtung

Versionsregeln wie --disable-auto-update major sind es nicht dienen nur als Ersatz – sie blockieren lediglich Versionssprünge und prüfen nie den nativen code. So werden native Änderungen in Minor- oder Patch-Releases weiterhin verteilt. Nutze --fail-on-incompatible oder --auto-min-update-version, um deine nativen Pakete zu prüfen.

Siehe Version-Targeting für die vollständige Auswahl an Targeting-Optionen.

Ähnliche Themen

Native + OTA-Workflow

Dev-/Production-Channels: Wann man sie behält --fail-on-incompatible, und wie man eine bewusste native Baseline ausliefert.

Auto OTA oder Native

Einbinden bundle releaseType in GitHub Actions oder GitLab, damit die CI den live update- vs. Capgo-Build wählt.

Version-Targeting

Liefern Sie nur kompatible Bundles aus – mit Channels, Semver-Regeln und der Metadata-Strategie.

Rollbacks

Setze einen Channel auf den letzten kompatiblen Build zurück, falls ein inkompatibles Bundle live gegangen ist.

Update-Typen

So arbeiten Timing, Delay-Bedingungen und Version-Blocking zusammen.

CLI: Bundle

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

Weiter zu Native Compatibility

Wenn du es nutzt Native-Kompatibilität um Live Updates sicher zu halten, verbinde es mit Version-Targeting um Bundles nach der nativen Version zu routen, Rollbacks um zu reagieren, wenn ein inkompatibles Bundle veröffentlicht wird, Update-Typen um Channel-Version-Blocking zu verstehen, sowie die Capgo CLI Bundle-Referenz für die Befehle compatibility und releaseType.