Capgo version_build vs version_name: Setup-Schritte

Capgo’s Versionsnamen wirken anfangs vielleicht umständlich: version_build ist die native App-Baseline, während version_name verfolgt das Bundle auf dem Gerät. Wenn du den Unterschied verstehst, kannst du vor dem Rollout prüfen, warum ein Gerät ein OTA-Update erhält – oder nicht.

Wir haben die Troubleshooting-Seiten von 5 Live-Update-Plattformen analysiert, darunter unsere eigene. Unsere Doku listet 7 benannte version_build-Mismatch-Codes, während die anderen vier 5, 2, 2 bzw. 0 haben. Mehr benannte Codes bedeuten weniger Raten, wenn ein version_build-Mismatch auftritt.

Inhaltsverzeichnis

• Schritt 1: version_build und version_name in Capgo finden
• Schritt 2: Native Baseline und das heruntergeladene Bundle identifizieren
• Schritt 3: Herkunft der nativen App-Version prüfen
• Schritt 4: Bundle-Version für Capgo festlegen und prüfen
• Schritt 5: Channel-Berechtigung vor dem Update-Rollout testen
• Schritt 6: Versionskonflikte diagnostizieren und Releases reproduzierbar machen
• FAQ
• Fazit

Schritt 1: version_build und version_name in Capgo finden

Betrachte diese zunächst als zwei verschiedene Fakten zu einer einzigen App-Installation. version_build sagt Capgo, welche native App-Version auf dem Gerät installiert ist. version_name sagt Capgo, welches JavaScript-Bundle das Gerät heruntergeladen hat. Sie können unterschiedliche Werte haben, und das ist oft beabsichtigt.

Im Versionsmodell von Capgo ist die native Version der Referenzpunkt für die Update-Berechtigung. Capgo vergleicht das dem Kanal zugewiesene Bundle mit dieser nativen Baseline. Die installierte Bundle-Version des Geräts hilft, die aktuelle Web-code zu identifizieren, ersetzt aber nicht die native Baseline in den Versionsregeln des Kanals.

Suche das Gerät auf der Devices-Seite der Capgo-Konsole und notiere beide Werte, bevor du mit der Fehlerbehebung beginnst. Vergleiche sie anschließend mit dem Ziel-Bundle des Kanals. Die Capgo-Kanalregeln erklären, wie die Zielversion eines Kanals abgeglichen wird mit version_build.

Halte die drei Werte in separaten Spalten in einer Release Note oder einem Testbericht. Wenn das Team eine generische „App-Version“ angibt, ist es leicht, das falsche Paar zu vergleichen. Für die Berechtigung vergleiche das Ziel-Bundle mit version_build. Für das installierte Web-code prüfe version_name.

Die Benennung von Capgo kann anders wirken als Android-Konventionen, wo Teams „build“ oft für eine aufsteigende Build-Nummer verwenden. Lies hier das Feld nach seiner Capgo-Rolle, nicht nach dem, was der Name suggeriert. Diese kleine Gewohnheit verhindert viel Verwirrung im Release-Prozess.

Schritt 2: Native Baseline und das heruntergeladene Bundle identifizieren

Bevor du einen Versionswert änderst, identifiziere, welches code nativ ist und welches code als Bundle ausgeliefert wird. Die native App ist das installierte iOS- oder Android-Binary. Das Bundle enthält die Web-Assets, die eine Capacitor App per OTA-Update erhalten kann.

Imagine a native app shipped with baseline 1.2.3. Ein späterer Web-Fix wird als Bundle hochgeladen 1.2.4. Capgo prüft, ob das Ziel-Bundle des Channels für die native Baseline zulässig ist 1.2.3. Wenn es zulässig ist, kann das Gerät dieses Bundle herunterladen. Nach der Installation version_name spiegelt das jetzt auf dem Gerät befindliche Bundle wider. Die native Baseline bleibt an die installierte Binary gebunden.

Dieser Unterschied ist wichtig, wenn ein Nutzer einen älteren App-Store-Build, aber ein neueres Web-Bundle hat. Das Bundle kann sich ändern, ohne die native Binary zu ersetzen, aber ein OTA-Update kann keine nativen code hinzufügen, die nicht in der App enthalten waren. Wenn eine Änderung ein neues Plugin oder eine native Einstellung erfordert, plane einen Native Build, statt einen Bundle-Upload als Ersatz zu behandeln.

Nutze diesen Quick-Check, wenn die Werte nicht synchron wirken:

• Bestätige, welche native Binary auf dem Testgerät installiert ist.
• Finde den Versionswert heraus, den Capgo als native Baseline erhält.
• Prüfe die Bundle-Version, die dem Channel des Geräts zugewiesen ist.
• Notiere die installierte Bundle-Version separat von beiden.

Ziehe keine Rückschlüsse auf die native Baseline aus package.json es sei denn, dein Build-Prozess kopiert diesen Wert gezielt in die native Version oder die Capgo-Konfiguration. Die Version eines JavaScript-Projekts und die im Store installierte App-Version können voneinander abweichen. Die richtige Quelle ist die, die deine App tatsächlich an Capgo sendet.

Sobald du die Baseline und das aktuelle Bundle benennen kannst, besteht die nächste Aufgabe darin, jeden Wert bis zu seiner Quelldatei zurückzuverfolgen. Dort zeigen sich meist die Plattformunterschiede.

Schritt 3: Herkunft der nativen App-Version prüfen

Für eine zuverlässige version_build, finde die native Version, die deine Capacitor-App meldet. Die Versionsdokumentation von Capgo beschreibt unterschiedliche Source-Keys für iOS und Android und nutzt den daraus resultierenden nativen Wert als Baseline für den OTA-Vergleich.

Auf iOS

Prüfen CFBundleShortVersionString in der App- Info.plist. In den meisten Xcode-Projekten ist dieser Key auf $(MARKETING_VERSION), sodass der Wert, den du tatsächlich bearbeitest, die Marketing Version des Targets ist. Überprüfe den Wert in der gebauten App und nicht nur in einem Template oder einer Datei, die dein Build überschreiben könnte.

Wenn ein Team das Xcode-Projekt aktualisiert, aber nicht den Wert, der in der App ankommt, kann die lokale Projektansicht korrekt aussehen, während die installierte Binary etwas anderes meldet. Vergleiche die Version in der generierten nativen App mit dem Wert, den dein Release-Prozess erwartet.

Auf Android

Prüfen defaultConfig.versionName in der Gradle-Konfiguration der Android-App. Dieser native Versionsname wird im OTA-Vergleich von Capgo verwendet. Verwechslung mit einer Android-Build-code oder einer unbekannten JavaScript-Paketversion vermeiden. Für diese Prüfung ist die entscheidende Frage, welchen Versionsnamen die native App sendet.

Eine gemeinsame Versionsrichtlinie kann helfen, beide Plattformen abzustimmen, aber nicht davon ausgehen, dass sie bereits eine gemeinsame Quelle nutzen. iOS und Android können separate Dateien, Build-Schritte oder Release-Zeitpläne haben. Vergleiche die Endwerte während des Release-Checks, besonders wenn eine Plattform einen anderen Store-Rollout-Zeitplan hat.

Einige Apps setzen die native Version explizit in capacitor.config.ts über den Versionswert in der Updater-Konfiguration. Die Capgo Semver-Tester beschreibt diese native Baseline als einen Wert, der aus der Konfiguration oder den nativen App-Metadaten stammen kann. Wenn deine App die nativen Metadaten überschreibt, dokumentiere diese Entscheidung, damit niemand erwartet, dass die Store-Version die Quelle ist.

Notieren Sie für jede Plattform die Quelldatei, den aufgelösten Wert und den Build, der ihn enthält. So lässt sich eine Abweichung nach einem Release leichter nachvollziehen, wenn das Repository bereits eine neuere Version enthält als die auf dem Testgerät installierte App.

Ändern Sie nur die Quelle, die Ihr Build tatsächlich liest. Das Bearbeiten einer veralteten Datei kann eine code-Prüfung vollständig aussehen lassen, während die gepackte native Version unverändert bleibt.

Schritt 4: Bundle-Version für Capgo festlegen und prüfen

Die Bundle-Version beschreibt das JavaScript-Update, nicht die installierte native Binärdatei. Capgo kann diese Version aus dem version Feld in package.json wenn Sie keine explizite Bundle-Version angeben. Die CLI-Option --bundle kann die Version festlegen, die beim Upload gesendet wird.

Wählen Sie einen Pfad und legen Sie ihn in Ihrem Release-Prozess klar fest. Wenn package.json die Quelle ist, erhöhen Sie dieses Feld vor dem Upload. Wenn CI eine Bundle-Version über die CLI übergibt, lassen Sie den Job die aufgelöste Version in seinem Release-Log ausgeben. Eine unbemerkte Mischung beider Pfade macht es schwerer nachzuvollziehen, warum der Channel einen bestimmten Wert erhalten hat.

Verwenden Sie semantische Versionierung in der vertrauten major.minor.patch Form, wie z. B. 1.2.3. Capgo-Channel-Strategien verwenden die Teile dieser Version, um zu entscheiden, ob ein Ziel-Bundle zu einer nativen Baseline passt. Ein Pre-Release-Suffix wie -beta.1 kann helfen, channel-spezifische Builds zu kennzeichnen, aber halte die Version parsebar und in deinen Release-Tools konsistent.

Überlege dir den Versionssprung vor dem Veröffentlichen:

• Verwenden Sie eine Patch-Änderung für einen kompatiblen Web-Fix innerhalb derselben Release-Linie.
• Nutze eine Minor-Änderung, wenn die Änderung zu einer neuen kompatiblen Feature-Linie gehört.
• Nutze eine Major-Änderung, wenn sich die Kompatibilitätsgrenze ändert und ältere native code das Bundle möglicherweise nicht unterstützen.

Diese Labels sind eine Team-Konvention, kein Weg, native Funktionen per OTA hinzuzufügen. Eine Versionsnummer kann nicht beweisen, dass ein Bundle für eine native App sicher ist. Halte tatsächliche Kompatibilitätsentscheidungen an code und die Abhängigkeiten im Binary gebunden.

Vergleiche vor dem Upload die Package-Version oder den CLI-Wert mit der Version, die nach dem Upload für das Bundle angezeigt wird. Prüfe auch den Channel, der es ausliefert. Ein korrekt benanntes Bundle in einen nicht vorgesehenen Channel hochzuladen kann trotzdem zu einem falschen Testergebnis führen.

Ungültige oder inkonsistente Strings erfordern Innehalten und Prüfen, nicht Raten. Behalte einen bekannt funktionierenden Release-Wert bei, korrigiere die Quelle und teste die aufgelöste Version, bevor du sie promotest.

Der Capgo CLI Befehlsreferenz ist hilfreich, wenn du den Upload in ein Skript einbindest, da die Bundle-Version Teil der Inputs des Release-Befehls ist.

Schritt 5: Channel-Berechtigung vor dem Update-Rollout testen

Channel-Eligibility ist ein Vergleich, kein Raten anhand dessen, welches Bundle neuer aussieht. Capgo prüft das Target-Bundle des Channels gegen die native Baseline, die als version_buildgesendet wurde. Das aktuell heruntergeladene Bundle, gemeldet als version_name, ist nicht die Baseline für diese Channel-Regeln.

Angenommen, eine installierte native App meldet 1.2.3, während ihr aktuelles Bundle 1.2.4 ist. Wenn ein Channel auf 1.2.5weist, muss das Target gegen die native Baseline geprüft werden, 1.2.3nicht nur gegen das aktuelle Bundle 1.2.4. Welche Targets erlaubt sind, hängt von der Update-Strategie des Channels ab.

Capgo dokumentiert Strategien wie major und minor, die Updates gegen die native Baseline einschränken. Bei der Strategie major kann ein Target mit einer höheren Major-Version blockiert werden. Bei der Strategie minor kann ein Target blockiert werden, das die Major- oder Minor-Linie der Baseline ändert. Prüfe die konfigurierte Strategie, statt davon auszugehen, dass jedes Bundle, das neuer aussieht, akzeptiert wird.

Teste die exakte Kombination, die du veröffentlichen willst:

1. Installiere den Native Build, der deine Zielgruppe repräsentiert.
2. Bestätige die native Baseline, die an Capgo gesendet wurde.
3. Ordne das Testgerät dem gewünschten Channel zu.
4. Prüfe das Channel-Ziel und seine Versionsstrategie.
5. Fordere ein Update an und bestätige das Ergebnis auf dem Gerät.

Führe denselben Check auf einer anderen nativen Baseline durch, wenn deine Nutzerbasis mehr als eine Store-Version nutzt. Ein Bundle, das für einen frischen Build funktioniert, kann für ein älteres Binary blockiert werden – das kann die beabsichtigte Sicherheitsregel sein.

Für breitere Releases starte mit einem Test-Channel oder einem begrenzten Rollout. Achte auf unerwartete Eligibility-Ergebnisse, bevor du die Zielgruppe erweiterst. Das Channel-Modell von Capgo ermöglicht es Teams, Bundles über Release-Channels zu steuern; halte das Ziel und die beabsichtigte native Linie jedes Channels in deinen Release Notes klar.

Wenn ein Testgerät nicht aktualisiert wird, prüfe seine Channel-Zuordnung und Versionswerte, bevor du erneut hochlädst. Das wiederholte Veröffentlichen desselben Bundles behebt keinen Baseline-Mismatch.

Schritt 6: Versionskonflikte diagnostizieren und Releases reproduzierbar machen

Wenn die Werte nicht deiner Erwartung entsprechen, verfolge sie in dieser Reihenfolge. Bestätige zuerst die native App-Version auf dem Gerät. Prüfe dann, ob ein Konfigurations-Override die Baseline ändert. Vergleiche anschließend die Bundle-Version, die Capgo erhalten hat, mit dem Channel-Ziel. Diese Abfolge trennt einen fehlerhaften Quellwert von einer Channel-Regel, die wie eingestellt funktioniert.

Häufige Ursachen umfassen das Bumpen package.json während die native Version unverändert bleibt, eine Plattform aus einem anderen Release-Branch baut und ein Gerät testet, das einem anderen Channel zugewiesen ist. Eine weitere Fehlerquelle ist es, jede Nummer als „Build-Version“ zu bezeichnen. Halte fest, welcher Wert nativ ist, welcher das hochgeladene Bundle ist und welcher aktuell installiert ist.

Mache die Versions-Inputs für CI/CD explizit. Lass die Pipeline die gewünschte Release-Version aus einer kontrollierten Quelle lesen und übergib sie dann an den Upload-Befehl oder aktualisiere das package-Feld vor dem Upload-Schritt. Protokolliere die ermittelte native Baseline und das Bundle-Target im Job-Output. Verlasse dich nicht auf den lokalen Zustand eines Entwicklers, den der Build-Server nicht sehen kann.

Nutze ein Release Gate, das fehlschlägt, wenn eine erforderliche Version fehlt oder ein Format hat, das dein Team nicht akzeptiert. Führe dann vor der Promotion einen Test-Upload in den richtigen Channel durch. Capgo unterstützt einen auf CLI basierenden Deployment-Flow, sodass Teams den Bundle-Upload in ihren bestehenden CI/CD-Job integrieren und ein sichtbares Command-Log behalten können.

Verwechsle diese Werte nicht mit der Version der Android-WebView-Engine. Unser @capgo/capacitor-webview-version-checker Plugin prüft, ob die WebView-Engine eines Geräts veraltet ist, und kann einen nativen Update-Prompt anzeigen. Das ist eine separate Frage von version_build und version_name, daher ersetzt dies niemals die Prüfung der nativen Baseline und des Ziel-Bundles des Channels.

Wenn du von einem Legacy-Schema migrierst, solltest du nicht alle bestehenden Werte auf einmal umbenennen. Mappe zuerst die alte native Version auf die native Baseline. Mappe anschließend das hochgeladene Web-Release auf die Bundle-Version. Teste repräsentative bestehende App-Builds gegen die Channel-Strategie, bevor du Nutzer darauf umleitest.

Führe ein kurzes Release-Log mit dem Source-Commit, der nativen Version, der hochgeladenen Bundle-Version, dem Channel und dem Testergebnis. Falls ein Release pausiert oder ein Rollback durchgeführt werden muss, hilft dieses Log dem Team zu identifizieren, welches Bundle wohin ging. Das macht das nächste Deployment zudem reproduzierbar, statt davon abhängig zu sein, dass sich jemand merkt, welche Datei geändert wurde.

FAQ

Was ist der Unterschied zwischen version_build und version_name in Capgo?

version_build ist die native App-Baseline, während version_name die aktuell heruntergeladene Bundle-Version ist. Capgo nutzt die native Baseline, wenn es das Target-Bundle eines Channels auf Kompatibilität prüft. Halte die beiden Werte in Logs und Release Notes getrennt, damit du genau weißt, welche native App installiert ist und welches Web-Bundle sie nutzt.

Steuert version_name, ob ein OTA-Update erlaubt ist?

Nein, die Channel-Version-Strategien von Capgo vergleichen das Target-Bundle mit version_build, der nativen Baseline. version_name identifiziert das aktuell heruntergeladene Bundle. Wenn ein Gerät kein Update erhält, prüfe die Baseline, das Channel-Target und die konfigurierte Strategie, bevor du den aktuellen Bundle-Wert änderst.

Woher bezieht Capgo die native Version?

Unter iOS liest Capgo CFBundleShortVersionString, das Xcode in der Regel automatisch aus MARKETING_VERSION. Auf Android stammt die native Version aus defaultConfig.versionName. Eine explizite Updater-Version in der Capacitor-Konfiguration kann den Wert ändern, den deine App sendet. Prüfe daher die gebaute App.

Woher erhält Capgo die Bundle-Version?

Capgo kann die version Feld in package.json wenn du keine explizite Bundle-Version übergibst. Du kannst die Version auch über die CLI angeben --bundle Option. Wählen Sie eine eindeutige Quelle für Ihren Release-Workflow und prüfen Sie die Version, die Capgo nach dem Upload erhalten hat.

Fazit

Nutzt version_build für die native Baseline und version_name für das installierte Bundle. Verifiziere vor deinem nächsten Rollout beide Werte auf einem Testgerät und vergleiche das Channel-Ziel mit der Baseline. Dieser eine Check kann eine Versionsunstimmigkeit erkennen, bevor sie ein breiteres Publikum erreicht.