Native Compatibility

Ein Capgo lebendes Update ersetzt sofort Ihre App’s JavaScript-Bundle jedoch kann es die native Teil Ihrer App – die Capacitor/Cordova-Plugins, native Abhängigkeiten und native Projekt-Konfiguration, 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 trotzdem liefern, es kann jedoch auf Geräten, die noch die ältere native Build laufen, abstürzen oder sich ungewöhnlich verhalten.

Diese Seite erklärt, wie Capgo native Kompatibilität detektiert, was eine inkompatible Aktualisierung für Ihre Benutzer bedeutet und wie Sie native Änderungen sicher ausliefern können.

Hinweis

Lebendliche Updates sind auf Änderungen an JavaScript-Bundles beschränkt. Wenn Sie native code — Hinzufügen oder Entfernen eines Plugins, Upgrade von Capacitor, oder Ändern der native Projekt-Konfiguration — aktualisieren müssen, müssen Sie ein neues Binär-Update über den üblichen App-Store-Verteilungsprozess einreichen.

Warum native Kompatibilität wichtig ist

Jedes Capacitor-App wird in zwei Schichten geliefert:

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

Ein Live-Update ersetzt nur die JavaScript-Schicht. Wenn das neue JavaScript eine native Plugin oder API aufruft, das nicht in der installierten Binärdatei kompiliert wurde, schlägt die Aufrufanfrage 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, daher kann ein Gerät, das die alte native Version läuft, nicht sicher ein Bundle ausführen, das gegen neue native code gebaut wurde.

Wie Capgo die Kompatibilität erkennt

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

• registriert sind Wenn sie übereinstimmen, ist der Änderungsvorschlag.
• sicher zum Übertrag über die Luftlinie Wenn ein Plugin hinzugefügt, entfernt oder eine neue Version aufgewendet wurde, ist das Bundle — diese Änderungen wirken sich nur aus, wenn Benutzer ein neues natives 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 jedes natives 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 für OK/FAIL (händisch in CI-Protokollen), und --package-json / --node-modules die richtigen Pfade in einem monorepo anzugeben.

Ein maschinenlesbares Urteil (CI) erhalten.

Für Pipelines: bundle releaseType faltet die Überprüfung in ein einzelnes 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

Geben Sie Ihrem Release-Pipeline eine Schranke: Verschicken Sie ein Live-Update, wenn es druckt, und lösen Sie ein natives Build aus, wenn es druckt OTAWas bedeutet ein inkompatibles Update für Ihre Benutzer? native.

Abschnitt mit dem Titel „Was bedeutet ein inkompatibles Update für Ihre Benutzer?“

Achtung

Standardmäßig wird bei der Erkennung von Inkompatibilitäten keine Blockierung der Uploads durchgeführt — wenn Sie ein natives-inkompatibles Bundle hochladen und es als aktives Build eines Kanals festlegen, Capgo wird es an Geräten auf diesem Kanal ausliefern. (Sie können dies in eine harte Schranke umwandeln mit --fail-on-incompatible — siehe Inkompatible Lieferungen verhindern unten.)

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

Capgo’s automatische Rückschaltung kann einen JavaScript-Fehler fangen, der vor dem Ausführen geworfen wurde notifyAppReady() läuft zwar, ist aber kein Ersatz für die Bereitstellung von kompatiblen nativen code — ein Mismatch, das später abstürzt oder natively abstürzt, kann daran vorbeikommen

Wie man native Änderungen sicher einsetzt

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

Wenn ein Bundle neue native code benötigt, bauen und submiten 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 die native Abhängigkeiten des Bundles und die Live-Update läuft richtig ab

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 die native Build raus ist, nicht mehr zu liefern. Siehe Rückgänge.

Verhindere inkompatible Lieferungen

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

Führen Sie die Upload-Verarbeitung in CI — --fail-on-incompatible

Fügen Sie die Flagge Ihrem bundle upload Schritt. Wenn die Bundle-native-Pakete nicht mit der Version des Kanals übereinstimmen, die derzeit live ist, schlägt der Upload mit einer nicht Nullen-Exit-Status und wird nichts verschifft — — also stoppt Ihre Pipeline Sie daran, einen OTA-Update stillschweigend zu veröffentlichen, der nicht wirksam werden kann, bis die Benutzer eine native Build installieren: Terminalfenster

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

Compatible uploads — and cases where the check can’t run (a new channel, or no remote metadata) — pass through unchanged. In an interactive terminal it offers the Capgo Builder native-build flow instead; declining fails. (Can’t be combined with --ignore-metadata-check.)

Gate lieferung durch native Version — metadata + --auto-min-update-version

Wenn Sie tun den native 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 auf jedem Upload durch und legt, wenn ein Bundle neue native code benötigt, den Update-Floor an, damit Geräte, die noch nicht die passende 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

Vorsicht

Versionen-Regeln wie --disable-auto-update major sind nicht ein Ersatz — sie blockieren nur Versionssprünge und untersuchen niemals natives __CAPGO_KEEP_0__, daher geht ein natives Update in einer Minor- oder Patchversion immer 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

Version Zielsetzung für die vollständige Liste der Zielsetzungsoptionen. Zugehörige

Abschnitt mit dem Titel “Zugehörige”

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

Rückgänge

Version Zielsetzung

Revert einen Kanal auf die letzte kompatible Build, wenn ein inkompatibles Bundle live ging.

Update Arten

Wie funktionieren die Anwendungen von Timing, Verzögerung und Versionsblockierung zusammen.

CLI: Bundle

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

Weiter von der Native Kompatibilität

Wenn Sie Native Kompatibilität verwenden um live Updates sicher zu halten, verbinden Sie es mit Version-Zielsystem um Bundles nach nativer Version zu routen, Wenn Sie Native Kompatibilität verwenden, um live Updates sicher zu halten, verbinden Sie es mit Version-Zielsystem, um Bundles nach nativer Version zu routen, Rollbacks um wiederherzustellen, wenn ein inkompatibles Bundle ausgeliefert wird, Update Arten um die Kanalversion zu blockieren, und die Capgo CLI Bundle-Referenz für die Kompatibilität und die releaseType-Befehle.