Native Kompatibilität

A Capgo Live-Update ersetzt Ihr App-Bundle sofort, aber es kann die native Teile Eurer App 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 Eure Benutzer bedeutet und wie man native Änderungen sicher verschicken kann.

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 Ihr native __CAPGO_KEEP_0__ aktualisieren müssen — ein Plugin hinzufügen oder entfernen, __CAPGO_KEEP_1__ upgraden oder die native Projekt-Konfiguration ändern — müsst Ihr ein neues Binär-Update über die übliche App-Store-Distribution-Vorgehensweise 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__

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, Plugin-Konfigurationen, die in Capacitor konfiguriert sind, native Plugins oder Abhängigkeiten, Capacitor selbst oder iOS/Android-Projektdateien. Eine praktische Überprüfung: Wenn sich der Änderung auf das native Projekt durch npx cap sync oder npx cap copy Seit wann ist OTA die bessere Wahl?

Bevor installierte Geräte es verwenden können, behandeln Sie es als native.	Ship with Capgo OTA?	Mit __CAPGO_KEEP_0__ OTA senden?
Weshalb	HTML, CSS, App-JavaScript, Bilder, Schriftarten und andere Web-Build-Assets	Ja
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 in iOS- oder Android-Projektdateien	Nein	Bestehende Benutzer benötigen eine neue Binärdatei aus den Stores.

Client-Plugins nach Stapel

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

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 der installierten Binärdatei.

Warum Nativkompatibilität wichtig ist

Capacitor-Anwendungen liefern in zwei Schichten ab:

• Die die native binäre Benutzer installieren sie von der App Store / Play Store. Es enthält Capacitor, Ihre native Plugins und die 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 Funktion oder API aufruft, die nicht in der installierten Binärdatei kompiliert wurde, schlägt die Aufruf bei Laufzeit fehl – was das Programm zum Absturz oder stillschweigend zu einem fehlerhaften Feature führen 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 eine neue Version hatte, ist das Bundle nicht native-kompatibel — 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 Entscheidung (CI)

Abschnitt mit dem Titel „Erhalten Sie eine maschinenlesbare Entscheidung (CI)“

verkleinert 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

Deine Releasepipeline sperren Sie auf dieser Grundlage: Versenden Sie ein Live-Update, wenn es druckt OTAund lösen Sie eine native Build aus, wenn es druckt native.

Wie bedeutet ein inkompatibles Update für Ihre Benutzer?

Achtung

Standardmäßig wird die Inkompatibilität nicht blockiert — wenn Sie ein native-inkompatibles Bundle hochladen und es als aktives Build eines Kanals setzen, __CAPGO_KEEP_0__ block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo den Geräten auf diesem Kanal aus. (Sie können dies in eine harte Sperre umwandeln, — siehe --fail-on-incompatible — see Verhindern Sie inkompatible Lieferungen unten.

Auf Geräten, die noch immer die ältere native Binärdatei laufen lassen Die fehlende native __CAPGO_KEEP_0__ kann Crashs oder gebrochene Funktionen verursachen — auch wenn die Aktualisierung heruntergeladen und angewendet wurde „mit Erfolg“. Dies ist der Grund, warum eine Live-Update live und geliefert werden kann, aber dennoch 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 Mangel, der später abstürzt oder natively abstürzt, kann es überlisten. 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.

Sektion mit dem Titel „Wie Sie native Änderungen sicher bereitstellen“

Publish a new native build (the real fix)

Wenn ein Bundle neue natives code benötigt, erstellen und übermitteln Sie ein neues Binärdatei an den App Store / Play Store (oder rebuilden Sie mit Capgo Cloud Build). Sobald die Benutzer die Binärdatei aktualisieren, passen sich die natives Abhängigkeiten des Bundles an und die Live-Update läuft korrekt.

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 der Flagge zu Ihrem bundle upload Schritt. Wenn die natives Pakete des Bundles nicht mit der derzeit liveen Version des Kanals übereinstimmen, wird der Upload Fällt mit einer Nicht-Null-Ausgabenummerung aus und wird nichts geliefert. — 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-native-Build-Flow 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), überspringe --fail-on-incompatible damit die Basisupload. Halte die Flagge auf jedem alltäglichen OTA- CI. Vollständiger Kanalworkflow: Native + OTA-Kanalworkflow.

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

Wenn Sie tun den native Build und das Bundle gemeinsam verschicken, legen Sie den Kanal auf die metadata Strategie und laden Sie mit --auto-min-update-versionCapgo führt die Kompatibilitätsprüfung bei jedem Upload durch und hebt bei einem Bundle, das neue native code benötigt, die Update-Schwelle an, damit 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

Versionen-Regeln wie --disable-auto-update major sind nicht eine Ersatzlösung — sie blockieren nur Versionssprünge und untersuchen niemals native code, daher geht ein native Änderung, die in einer Minor- oder Patchversion verschickt wird, weiter. --fail-on-incompatible oder --auto-min-update-versionoder

um den vollständigen Satz an Zieloptionen zu sehen. zugehörig Abschnitt mit dem Titel ‘Zugehörig’

Natives + OTA-Workflow

, und wie man eine absichtliche native Basislinie verschicken kann.

Versionzielung --fail-on-incompatiblefür die vollständige Menge an Zieloptionen.

Auto OTA oder Native

Wire bundle releaseType GitHub in Aktionen oder GitLab, damit CI die Live-Update-Verschiebung erkennt, oder Capgo Build.

Versionziel

context

Verwenden Sie Kanäle, semver-Regeln und die Metadatenstrategie, um nur kompatible Pakete bereitzustellen.

Rückgänge

Rufen Sie einen Kanal auf das letzte kompatible Build zurück, wenn ein inkompatibles Paket live ging.

Update-Typen

CLI: bundle

__CAPGO_KEEP_0__: Paket

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

Wenn Sie Native Kompatibilität verwenden Native Kompatibilität um Live-Updates sicher zu halten, verbinden Sie sie mit Version-Zielsetzung context um Pakete nach nativer Version zu routen, Rückgänge um wiederherzustellen, wenn ein inkompatibles Paket abgesendet wird, Update-Typen Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ Paketreferenz für die Kompatibilität und releaseType-Befehle