Native Kompatibilität

Ein Capgo live update ersetzt sofort Ihre App-Bundle JavaScript-Bundle unverzüglich, aber es kann die native Teile Ihrer App – die Capacitor Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfigurationen, die in das installierte Binärdatei kompiliert wurden. Wenn ein neues Bundle native code erwartet, die die installierte Binärdatei nicht hat, ist das Bundle native-inkompatibel: Capgo kann es immer noch liefern, aber es kann auf Geräten, die noch die ältere native Ausführung laufen, abstürzen oder sich ungewöhnlich verhalten.

Diese Seite 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.

Anmerkung

Live Updates sind auf JavaScript-Bundle-Änderungen beschränkt. Wenn Sie native code — das Hinzufügen oder Entfernen eines Plugins, das Upgrade von Capacitor, oder die Änderung der native Projekt-Konfiguration — benötigen, müssen Sie eine neue Binärdatei über den üblichen App-Store-Verteilungsprozess einreichen.

Kurzfassung: 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 beschränkt, die in diesem Output gebündelt sind, senden Sie es als live update.

Verwenden Sie eine native App-Veröffentlichung, wenn eine Änderung capacitor.config.ts, die Plugin-Konfiguration, die in Capacitor-Konfiguration gespeichert ist, native Plugins oder Abhängigkeiten, Capacitor selbst oder iOS/Android-Projektdateien aktualisiert. Eine praktische Überprüfung: Wenn die Änderung das native Projekt über npx cap sync oder npx cap copy vor installierten Geräten verwenden kann, behandeln Sie es als native.

Änderung	Mit Capgo OTA senden?	Weshalb
HTML, CSS, Anwendungs-JavaScript, Bilder, Schriftarten und andere Web-Build-Assets	Ja	Sie werden aus dem Web-Bundle zur Laufzeit geladen.
Rein-JavaScript-Paketänderungen, die in Ihr Web-Output eingebunden sind	Ja	Die generierte JavaScript-Code ist Teil des Web-Bundles.
capacitor.config.ts Änderungen	Nein	Capacitor-Konfiguration wird in die native App zum Zeitpunkt der Erstellung gelesen.
Hinzufügen, Entfernen oder Upgraden von Capacitor/Cordova-Plugins	Nein	Die installierte native Binärdatei muss die entsprechende native code-Version enthalten.
iOS- oder Android-Projektdateien wurden geändert	Nein	Bestehende Nutzer benötigen ein neues Binärdatei aus den Stores.

Client-Plugins nach Stapel

Capgo stellt dedizierte Updater-Klienten für jeden Hybrid-Runner bereit:

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

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

Wozu native Kompatibilität wichtig ist

Jedes Capacitor-Programm wird in zwei Schichten geliefert:

• Die native Binärdatei die Benutzer aus dem App Store / Play Store installieren. Sie enthält Capacitor, Ihre native Plugins und native Konfiguration.
• Die JavaScript-Bundle (Ihre Webanwendung), das Capgo über die Luft aktualisieren kann.

Ein live update ändert 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 oder stillschweigend zu einem fehlerhaften Feature führen 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 kompiliert wurde.

Wie Capgo Kompatibilität erkennt

Wenn Sie ein Paket hochladen — oder die Überprüfung manuell durchführen — vergleicht Capgo die nativierte Pakete in Ihrem lokalen Projekt (Ihre Capacitor/Cordova-Plugins und ihre Versionen) gegenüber den für das Bundle aufgezeichneten native Paketen currently live on the channel:

• Wenn sie übereinstimmen, ist die Änderung JavaScript-only und sicher zum Übertrag über die Luft.
• Wenn ein Plugin hinzugefügt, entfernt oder eine Version geändert wurde, ist das Paket native-inkompatibel — diese Änderungen wirken sich nur aus, wenn die Benutzer ein neues natives Binärdatei installieren.

Überprüfung von 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 OK/FAIL (nützlich in CI-Protokollen), und --package-json / --node-modules Zu den richtigen Pfaden in einem monorepo hinweisen.

Erhalte eine maschinenlesbare Verurteilung (CI)

Für Pipelines, bundle releaseType verkleinert die Überprüfung auf einen 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

Shipen Sie Ihren Release-Pipeline auf diese Weise: schicken Sie ein live update aus, wenn es druckt. OTA, und löst eine native Build aus, wenn es druckt. native.

und lösen Sie eine native Build aus , wenn es druckt

Caution

Standardmäßig wird die Inkompatibilität erkannt not blockiert die Hochladen — wenn Sie ein native-inkompatibles Bundle hochladen und es als aktives Build eines Kanals setzen , Capgo liefern Sie es zu Geräten auf diesem Kanal. (Sie können dies in einen harten Gate umwandeln) --fail-on-incompatible — see Verhindere inkompatible Lieferungen below.)

Auf Geräten, die noch immer die Auf Geräten, die noch immer die, 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 __CAPGO_KEEP_0__’s Kann einen vorher geworfenen JavaScript-Fehler fangen notifyAppReady() läuft, aber es ist kein Ersatz für die Lieferung von kompatiblen nativen code — ein Missmatch, das später abstürzt, oder abstürzt, kann es übersehen.

Wie man native Änderungen sicher ausliefern kann

Veröffentlichen Sie eine neue native Build (die echte Lösung)

Wenn ein Bundle neue native code benötigt, bauen und submit Sie eine neue Binärdatei in den App Store / Play Store (oder rebuilden Sie mit Capgo Cloud Build). Sobald die Benutzer die Binärdatei aktualisieren, passen sich die native Abhängigkeiten des Bundles an und live update läuft richtig.

Rückgängig machen, wenn ein inkompatibles Bundle bereits live ist

Wenn ein inkompatibles Bundle bereits auf einem Kanal aktiv ist, kehren Sie den Kanal zur letzten kompatiblen Build zurück, um es bis zum Ausstoß des native Builds auszuschenken. Siehe Rücksetzungen.

Verhindern Sie inkompatible Lieferungen

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

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

Hinzufügen Sie die Flagge zu Ihrem bundle upload Schritt. Wenn die Pakete des Bundles nicht mit der aktuellen Live-Version des Kanals übereinstimmen, schlägt die Upload- mit einem Nicht-Null-Ausgang fehl und wird nicht verschifft — so wird Ihre Pipeline verhindert, dass Sie einen OTA-Update veröffentlichen, der erst nachdem die Benutzer eine native Installation durchführen, wirksam wird:

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

Kompatible Uploads — und Fälle, in denen der Check nicht durchgefü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; Ablehnen schlägt fehl. (Kann nicht mit --ignore-metadata-check.)

Tipps

Wenn Sie vorsätzlich braucht ein Bundle, das sich von den im Kanal lebendigen Paketen unterscheidet (neuer Plugin, Capacitor-Upgrade usw.), überspringen --fail-on-incompatible Für diese Basisupload. Halten Sie die Flagge bei jedem alltäglichen OTA- CI: Vollständiger Kanalworkflow: Nativ + OTA-Kanalworkflow.

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

Wenn Sie machen den nativen Build und das Bundle zusammen schicken, setzen 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, wenn ein Bundle neue native code benötigt, die Aktualisierungsplattform an, damit Geräte, die noch nicht die entsprechende native Version installiert haben, sie 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

Versionierungsregeln wie --disable-auto-update major sind keine Ersatz – sie blockieren nur Versionssprünge und untersuchen niemals 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-versionum Ihre native Pakete zu überprüfen.

Siehe Zielversionierung zur vollständigen Liste der Zielversionierungsoptionen.

Zugehörige

Native + OTA Workflow

Dev/Produktionskanäle, wann behalten --fail-on-incompatible, und wie man ein bewusstes natives Basislevel versendet.

Auto OTA oder Native

Wire bundle releaseType GitHub Aktionen oder GitLab, damit CI live update gegen Capgo Build auswählt.

Versionsziel

Verwenden Sie nur kompatible Pakete, indem Sie Kanäle, Semver-Regeln und die Metadatenstrategie verwenden.

Rollbacks

Ein Kanal auf die letzte kompatible Version zurücksetzen, wenn ein inkompatibler Bundle live ging.

Aktualisierungsarten

Wie funktionieren Timing, Verzögerungskriterien und Versionsblockierungen zusammen.

CLI: Paket

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

Fortsetzung von Native-Kompatibilität

Wenn Sie Native-Kompatibilität Native-Kompatibilität zum sicheren Live-Update verwenden, verbinden Sie es mit Version-Ziel zu Routen von Bundeln nach nativer Version. Rollbacks to recover when an incompatible bundle ships, Aktualisierungsarten um das Kanalversion-Blockieren zu verstehen und die Capgo CLI Bundle-Referenz für die Kompatibilitäts- und releaseType-Befehle.