Native Compatibility

Ein Capgo Live-Update ersetzt Ihre App’s JavaScript-Bundle schnell, aber es kann 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, wird das Bundle als native-inkompatibel: Capgo kann es immer noch liefern, aber es kann 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 erkennt, was eine inkompatible Aktualisierung für Ihre Benutzer bedeutet und wie Sie native Änderungen sicher verschicken können.

Hinweis

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

TLDR: 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, die in diesem Output gebündelt sind, auswirken, senden Sie es als Live-Update.

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

Ändern	Mit Capgo OTA liefern?	Warum
HTML, CSS, Anwendungs-JavaScript, Bilder, Schriftarten und andere Web-Build-Assets	Ja	Sie werden zur Laufzeit aus dem Web-Bundle geladen.
Rein-JavaScript-Paket-Änderungen in Ihrem Web-Ausgang gebündelt	Ja	Das generierte JavaScript ist Teil des Web-Bundles.
capacitor.config.ts Änderungen	Nein	Capacitor-Konfiguration wird in die native App zum Build-Zeit gelesen.
Capacitor/Cordova-Plugins hinzufügen, entfernen oder upgraden	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 liefert dedizierte Updater-Klienten für jeden Hybrid- Runtime:

Plugin	Wenn Sie möchten, dass __CAPGO_KEEP_0__ Ihre iOS/Android-Anwendungen verwendet
@capgo/capacitor-updater	Capacitor ships dedicated updater clients for each hybrid runtime: ist nicht übersetzt, da es ein Satz ist, der nicht übersetzt werden sollte.
@capgo/cordova-updater	iOS 7+ / Android 13+ Apps für Cordova
@capgo/electron-updater	Elektron-Desktop-Apps

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

Warum native Kompatibilität wichtig ist

Every Capacitor app ships in two layers:

• nativ binäre Benutzer installieren es aus dem App Store / Play Store. Es enthält __CAPGO_KEEP_0__, Ihre nativen Plugins und die native Konfiguration. users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• JavaScript-Bundle (Ihre Web-App), die __CAPGO_KEEP_0__ über die Luft über aktualisieren kann. (your web app) that Capgo can update over the air.

A live update ersetzt nur die JavaScript-Schicht. Wenn die neue JavaScript-Anwendung eine native Plugin oder API aufruft, das nicht in der installierten Binärdatei kompiliert wurde, schlägt die Anfrage 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 Paket ausführen, das gegen native code gebaut wurde.

Wie Capgo Kompatibilität erkennt

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

• registriert sind Wenn sie übereinstimmen, ist die Änderung nur JavaScript-basiert und.
• sicher zum Übertrag über die Luft Wenn ein Plugin hinzugefügt, entfernt oder eine Version geändert wurde, ist das Paket native-inkompatibel

Überprüfen Sie aus dem 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 (handy in CI-Protokollen), und --package-json / --node-modules um auf die richtigen Pfade in einem monorepos-Verzeichnis zu zeigen.

Erhalten Sie eine maschinelle Lesbarkeit (CI)

Für Pipelines bundle releaseType faltet die Überprüfung in ein einzelnes Wort ein:

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, und lösen Sie einen nativen 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?“

Vorsicht

Standardmäßig wird die Inkompatibilität nicht blockiert, wenn Sie ein natives-inkompatibles Bundle hochladen und es als aktives Build eines Kanals festlegen, __CAPGO_KEEP_0__ wird es dennoch an Geräten auf diesem Kanal liefern. (Sie können dies in eine Haltelinie umwandeln — siehe unten 'Inkompatible Lieferungen verhindern'.) auf block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo auf wenn --fail-on-incompatible wenn dies weshalb

weshalb warnen, 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 automatische Rollover kann einen JavaScript-Fehler fangen, der vorher geworfen wurde notifyAppReady() läuft, aber es ist kein Ersatz für die Lieferung von kompatiblen nativen code — ein Mismatch, das später abstürzt oder natively abstürzt, kann es umgehen.

Wie man native Änderungen sicher einsetzt

Veröffentlichen Sie ein neues natives Build (die wirkliche Lösung)

Wenn ein Bundle neue native code benötigt, bauen und senden Sie ein neues Binärformat an die App Store / Play Store (oder rebuilden Sie mit Capgo Cloud Build). Sobald die Benutzer das Binärformat aktualisieren, passen die nativen Abhängigkeiten des Bundles und das 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 Erscheinen der nativen Build auszuschenken. Siehe Rücksetzungen.

Verhindere inkompatible Lieferungen

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

Fehlermeldung im CI — --fail-on-incompatible

Fügen Sie die Flagge Ihrem bundle upload Schritt. Wenn die Bundle-native-Pakete nicht mit der aktuellen Live-Version des Kanals übereinstimmen, fällt die Upload- mit einer nicht-Null-Ausgabenummer und nichts wird verschickt —

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.)

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 Ihnen stattdessen den __CAPGO_KEEP_0__-Builder-native-Build-Flow an; Ablehnung führt zum Scheitern. (Kann nicht mit "Gate delivery by native version —" kombiniert werden.) metadata + --auto-min-update-version

Wenn Sie tun den nativen Build und das Bundle gemeinsam versenden, legen Sie den Kanal auf die metadata Strategie und laden Sie mit --auto-min-update-version. Capgo führt bei jedem Upload eine Kompatibilitätsprüfung durch und hebt bei einem Bundle, das neue native code benötigt, die Aktualisierungsstufe 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

Vorsicht

Versionierungsregeln wie --disable-auto-update major sind nicht ein Ersatz — sie blockieren nur Versionssprünge und untersuchen niemals natives code, also geht ein natives Update in einem Minor- oder Patch-Release immer raus. Verwenden Sie --fail-on-incompatible oder --auto-min-update-version, die Ihre native Pakete überprüfen.

Siehe Versionziel für die vollständige Liste der Zieloptionen.

Zugehörige

Versionziel

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

Rückgänge

Rückgängig machen Sie einen Kanal auf das letzte kompatible Build, wenn ein inkompatibles Bundle live gegangen ist.

Aktualisierungstypen

Wie funktionieren die Anwendung von Zeitverzögerung, Verzögerungsbedingungen und Versionsblockierung zusammen.

CLI: bundle

Referenz für die Kompatibilität des Bundles, releaseType und Uploadoptionen.

Weitermachen von Native Kompatibilität

Wenn Sie Native Kompatibilität verwenden, um lebendige Updates sicher zu halten, verbinden Sie es mit Version-Zielsetzung, um Bundles nach nativer Version zu routen, Native Kompatibilität Version-Zielsetzung Rückgängigmachung Um lebendige Updates sicher zu halten, verbinden Sie es mit Version-Zielsetzung, um Bundles nach nativer Version zu routen. Um lebendige Updates sicher zu halten, verbinden Sie es mit Version-Zielsetzung, um Bundles nach nativer Version zu routen. um wiederherzustellen, wenn ein inkompatibles Bundle abgesendet wird, Update-Typen um den Kanalversionen zu verstehen, die Blockierung und die Capgo CLI Bezug auf das Bundle für die Kompatibilität und die releaseType-Befehle.