Native Compatibility

Ein Capgo Live-Update ersetzt die JavaScript-Bundle Ihres Apps. Ein __CAPGO_KEEP_0__ live update ersetzt die JavaScript-Bundle Ihres Apps. unmittelbar, aber es kann die native Komponente deiner App nicht ändern — die __CAPGO_KEEP_0__/Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfiguration, die in die installierte Binärdatei kompiliert werden. Wenn eine neue Bundle native __CAPGO_KEEP_1__ erwartet, die die installierte Binärdatei nicht hat, ist das Bundle als inkompatibel markiert. native Ein Teil deiner App — die Capacitor/Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfiguration, die in die installierte Binärdatei kompiliert werden. Wenn eine neue Bundle native code erwartet, die die installierte Binärdatei nicht hat, ist das Bundle als inkompatibel markiert. native-incompatible: Capgo kann es immer noch liefern, aber es kann auf Geräten, die noch die ältere native Build laufen, abstürzen oder sich falsch verhalten.

Diese Seite erklärt, wie Capgo native Kompatibilität erkennt, was eine inkompatible Aktualisierung für deine Benutzer bedeutet und wie du native Änderungen sicher verschicken kannst.

Hinweis

Live-Updates sind auf Änderungen an JavaScript-Bundles beschränkt. Wenn du native code — indem du ein Plugin hinzufügst oder entfernst, Capacitor upgradest oder die native Projekt-Konfiguration änderst — aktualisieren musst, musst du ein neues Binärbuild durch den üblichen App-Store-Distribution-Prozess einreichen.

TLDR: OTA oder native?

Capgo kann Dateien aus deinem generierten Web-Build-Ordner senden. Wenn die Änderung nur auf HTML, CSS, JavaScript, Assets oder reinen JavaScript-Paketen, die in diesem Output gebündelt sind, Einfluss hat, verschicke sie als Live-Update.

Wenn eine Änderung eine native App aktualisiert capacitor.config.tsPlugin-Konfiguration in Capacitor Konfiguration, native Plugins oder Abhängigkeiten, Capacitor selbst oder iOS/Android-Projektdateien gespeichert. npx cap sync Ein praktischer Check: Wenn die Änderung die native App über npx cap copy oder

vorher auf installierten Geräten verwenden kann, behandeln Sie es als native.	Ship with Capgo OTA?	Mit __CAPGO_KEEP_0__ OTA liefern?
Wozu	HTML, CSS, App-JavaScript, Bilder, Schriftarten und andere Web-Build-Assets	Ja
Sie werden zum Laufzeit aus dem Web-Bundle geladen.	Rein-JavaScript-Paket-Änderungen in Ihrem Web-Ausgang gebündelt werden.	The generierte JavaScript ist Teil der Web-Bundle.
capacitor.config.ts Änderungen	Nein	Capacitor-Konfiguration wird bei der Zeit der native App gelesen.
Hinzufügen, entfernen oder Capacitor/Cordova-Plugins aktualisieren	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.

Client-Plugins nach Stack

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

Plugin	Verwenden Sie wenn
@capgo/capacitor-updater	Capacitor-iOS/Android-Anwendungen
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ Apps
@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 dem installierten Binärdatei.

Warum native Kompatibilität wichtig ist

Jede Capacitor-Anwendung 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 die native Konfiguration.
• Die JavaScript-Bundle (Ihre Web-Anwendung) das Capgo über die Luft aktualisieren kann.

Ein Live-Update ersetzt nur die JavaScript-Schicht. Wenn das neue JavaScript eine native Komponente oder API aufruft, die nicht in der installierten Binärdatei kompiliert wurde, schlägt die Aufrufanfrage 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 Pakete im lokalen Projekt (Ihre Capacitor/Cordova-Plugins und ihre Versionen) mit den native Paketen, die für das Bundle aktuell im Kanal:

• registriert sind. Wenn sie übereinstimmen, ist die Änderung nur auf JavaScript-Basis sicher zum Luftübertrag über die Luft zu schicken.
• Wenn ein Plugin hinzugefügt, entfernt oder eine Versionsänderung vorgenommen wurde, ist das Bundle nicht für native Geräte geeignet — diese Änderungen wirken sich erst dann aus, wenn die Benutzer ein neues natives Binärprogramm installieren.

Überprüfe von der CLI

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

Die CLI druckt eine Tabelle jedes native Pakets 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 (handy in CI-Protokollen), und --package-json / --node-modules um auf die richtigen Pfade in einem monorepos-Verzeichnis zu zeigen.

Erhalten Sie eine maschinenlesbare Verurteilung (CI)

Für Pipelines bundle releaseType kollabiert 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

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

Was bedeutet ein inkompatibles Update für Ihre Benutzer

Vorsicht

Standardmäßig wird die Inkompatibilität nicht blockiert — wenn Sie ein natives-inkompatibles 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 an Geräten auf diesem Kanal ausgeliefert. (Sie können dies in einen harten Gate umwandeln mit — siehe --fail-on-incompatible Inkompatible Lieferungen verhindern unten.) Inkompatible Lieferungen verhindern

Auf Geräten, die noch immer mit ältere native Binärdatei, das fehlende native code kann zu Crashes oder gebrochenen Funktionen führen – trotzdem wurde die Aktualisierung heruntergeladen und angewendet „mit Erfolg“. Dies ist der Grund, warum eine Live-Update live und geliefert werden kann, aber dennoch die App für bestehende Nutzer kaputt machen kann, und warum Capgo Sie warnen kann, wenn ein inkompatibles Bundle live geht.

Capgo's Automatische Rollback-Funktion Kann einen vor dem Ausführen 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 an ihm vorbeikommen.

Wie man native Änderungen sicher bereitstellt

Ein neues natives Build veröffentlichen (die wahre Lösung)

Wenn eine Bundle eine neue native code benötigt, müssen Sie ein neues Binärdatei zum App Store / Play Store hochladen (oder mit Capgo Cloud Build neu erstellen). Sobald die Benutzer die Binärdatei aktualisieren, passen sich die native Abhängigkeiten der Bundle an und die Live-Update-Funktion funktioniert wie erwartet.

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

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

Verhindere inkompatible Lieferungen

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

Fehlermeldung im CI — --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, schlägt die Upload- mit einer nicht-Null-Ausgabe fehl und wird nichts geliefert — also hält Ihre Pipeline Sie davon ab, ein OTA-Update stillschweigend zu veröffentlichen, das erst nach dem Installieren eines nativen Builds wirksam werden kann: — fügen Sie die Flagge Ihrem

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 scheitert. (Kann nicht mit --ignore-metadata-check.)

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

Wenn Sie den native Build und das Bundle zusammen schicken, legen Sie den Kanal auf die metadata Strategie und laden Sie mit --auto-min-update-version. Capgo führt die Kompatibilitätsprüfung auf jedem Upload durch und, wenn ein Bundle neue native code benötigt, hebt es den Update-Fußboden an, damit Geräte, die noch nicht die entsprechende native Build 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

Achtung

Versionierungsregeln wie --disable-auto-update major sind keine Ersatz — sie blockieren nur Versionssprünge und überprüfen keine native __CAPGO_KEEP_0__, daher geht ein native Änderung, die in einem Minor- oder Patch-Release ausgeliefert wird, immer noch raus. Verwenden Sie 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 , die Ihre native Pakete überprüfen. --auto-min-update-versionSiehe

Versionzielung für die vollständige Liste der Zielmöglichkeiten. Zugehörige

Sektion mit dem Titel “Zugehörige”

Auto OTA oder Native

Wire bundle releaseType so in GitHub Aktionen oder GitLab, damit CI live Updates erkennt anstatt Capgo Build.

Version Zielsetzung

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

Rückgänge

Rückgängig machen Sie einen Kanal auf den letzten kompatiblen Build, wenn ein inkompatibles Paket live ging.

Update Arten

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

CLI: Paket

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

Fortsetzung von Native Kompatibilität

Wenn Sie Native-Kompatibilität benutzen, 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 inkompatibles Bundle abgesandt wird, Update-Typen um den Kanalversionen zu verstehen, die Blockierung und das Capgo CLI Bundle-Bezug für die Kompatibilität und die releaseType-Befehle.