CapgoDie Versionsnamen können anfangs verwirrend wirken: version_build ist die native App-Baseline, während version_name das Bundle auf dem Gerät trackt. Wenn du den Unterschied kennst, 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, inklusive unserer eigenen, und festgestellt, dass unsere Dokumentation 7 benannte version_build-Mismatch-Codes auflistet – im Vergleich zu 5, 2, 2 und 0 bei den anderen vier. Mehr benannte Codes bedeuten weniger Rätselraten bei einem version_build-Mismatch.
Inhaltsverzeichnis
- Schritt 1: version_build und version_name in Capgo finden
- Schritt 2: Native Baseline und das heruntergeladene Bundle identifizieren
- Schritt 3: Prüfen, woher deine native App-Version stammt
- Schritt 4: Die Bundle-Version festlegen, die Capgo erhält
- 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 App-Installation. version_build sagt Capgo, welche native App-Version auf dem Gerät ist. version_name sagt Capgo, welches JavaScript-Bundle das Gerät heruntergeladen hat. Diese können unterschiedliche Werte haben, was oft so gewollt ist.
Im Versionsmodell von Capgo dient die native Version als Referenzpunkt für die Update-Berechtigung. Capgo vergleicht das einem Channel zugewiesene Bundle mit dieser nativen Baseline. Die installierte Bundle-Version des Geräts hilft dabei, den aktuellen Web-code zu identifizieren, ersetzt jedoch nicht die native Baseline in den Versionsregeln des Channels.
Suche das Gerät auf der Devices-Seite der Capgo Console und notiere beide Werte vor der Fehlersuche. Vergleiche sie anschließend mit dem Ziel-Bundle des Channels. Der Capgo Channel-Regeln erklären, wie die Zielversion eines Channels gegen version_build.
| Wert | Was es repräsentiert | Nutze es, um zu beantworten | Typische Quelle |
|---|---|---|---|
version_build |
An Capgo gesendete native App-Baseline | Kann diese native App das Ziel-Bundle des Channels erhalten? | Native App-Version oder ein expliziter Capacitor Konfigurationswert |
version_name |
Aktuell heruntergeladenes JavaScript-Bundle | Welche Bundle-Version ist aktuell installiert? | Beim Upload ermittelte Bundle-Version |
| Channel-Ziel | Dem Channel des Geräts zugewiesenes Bundle | Nach welcher Version sucht Capgo für ein Update? | Aktuelle Channel-Zuweisung |
Halte die drei Werte in Release Notes oder Testberichten in separaten Spalten. Wenn das Team nur eine generische „App-Version“ angibt, vergleicht man leicht das falsche Paar. Prüfe die Berechtigung, indem du das Ziel-Bundle mit version_buildvergleichst. Für das installierte Web-code prüfe version_name.
Die Benennung von Capgo weicht eventuell von Android-Konventionen ab, bei denen Teams oft „Build“ für eine fortlaufende Nummer nutzen. Lies das Feld hier nach seiner Capgo-Rolle, nicht nach dem Namen. Diese Gewohnheit verhindert Verwirrung beim Release.
Schritt 2: Native Baseline und heruntergeladenes Bundle identifizieren
Bevor du einen Versionswert änderst, identifiziere, welches code nativ ist und welches code als Bundle ausgeliefert wird. Die native App ist die installierte iOS- oder Android-Binary. Das Bundle enthält die Web-Assets, die eine Capacitor App via OTA-Update erhält.
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 den Native Baseline zulässig ist 1.2.3. Wenn es berechtigt ist, kann das Gerät dieses Bundle herunterladen. Nach der Installation version_name wird das Bundle nun auf dem Gerät reflektiert. Der 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 ein, anstatt ein Bundle-Upload als Ersatz zu nutzen.
Nutze diesen Quick-Check, wenn die Werte nicht synchron erscheinen:
- 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 anderen.
Leite den Native Baseline nicht von 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 auseinanderlaufen. Die richtige Quelle ist die, die deine App tatsächlich an Capgo sendet.
Sobald du die Baseline und das aktuelle Bundle benennen kannst, geht es als Nächstes darum, jeden Wert bis zu seiner Quelldatei zurückzuverfolgen. Dort zeigen sich meist die Plattformunterschiede.
Schritt 3: Prüfen, woher deine native App-Version kommt
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üfe 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. Prüfe den Wert in der gebauten App, 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üfe defaultConfig.versionName in der Gradle-Konfiguration der Android-App. Dieser native Version Name wird für den OTA-Vergleich von Capgo verwendet. Verwechsle ihn nicht mit einem Android Build code oder einer nicht zusammenhängenden JavaScript-Package-Version. Entscheidend für diesen Check ist, welchen Version Name die native App sendet.
Eine gemeinsame Version-Policy kann helfen, beide Plattformen synchron zu halten, aber gehe nicht davon aus, dass sie bereits dieselbe Quelle nutzen. iOS und Android können unterschiedliche Dateien, Build-Schritte oder Release-Zeitpläne haben. Vergleiche die finalen Werte während des Release-Checks, besonders wenn eine Plattform einen anderen Store-Rollout-Plan hat.
Einige Apps setzen die native Version explizit in capacitor.config.ts über den Version-Wert in der Updater-Konfiguration. Der Capgo Semver-Tester beschreibt diesen nativen Baseline als 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.
Notiere dir für jede Plattform die Quelldatei, den aufgelösten Wert und den Build, der ihn enthält. Das macht es einfacher, einen Mismatch nach einem Release zurückzuverfolgen, wenn das Repository eventuell schon eine neuere Version enthält als die App auf dem Gerät eines Testers.
Ändere nur die Quelle, die dein Build auch tatsächlich ausliest. Das Editieren einer veralteten Datei kann dazu führen, dass ein code Review vollständig aussieht, während die verpackte native Version unverändert bleibt.
Schritt 4: Bundle-Version festlegen und prüfen, die Capgo erhält
Die Bundle-Version beschreibt das JavaScript-Update, nicht die installierte native Binary. Capgo kann diese Version aus dem version Feld in package.json übernehmen, wenn du keine explizite Bundle-Version angibst. Die CLI- --bundle Option kann die Version festlegen, die beim Upload gesendet wird.
Pick one path and make it clear in your release process. If package.json die Quelle ist, erhöhe diesen Wert vor dem Upload. Wenn die CI eine Bundle-Version über die CLI übergibt, sollte der Job die aufgelöste Version in seinem Release-Log ausgeben. Ein stillschweigender Mix aus beiden Wegen erschwert die Fehlersuche, warum ein Channel einen bestimmten Wert erhalten hat.
Nutze Semantic Versioning in der gewohnten major.minor.patch Form, wie zum Beispiel 1.2.3. Die Capgo Channel-Strategien nutzen die Teile dieser Version, um zu entscheiden, ob ein Target-Bundle zu einer nativen Baseline passt. Ein Pre-release-Suffix wie -beta.1 kann helfen, channel-spezifische Builds zu kennzeichnen, aber achte darauf, dass die Version für deine Release-Tools parsebar und konsistent bleibt.
Überlege dir die Versionierung vor dem Publishing:
- Nutze eine Patch-Änderung für einen kompatiblen Web-Fix innerhalb derselben Release-Line.
- Nutze eine Minor-Änderung, wenn die Änderung zu einer neuen, kompatiblen Feature-Reihe gehört.
- Nutze eine Major-Änderung, wenn sich die Kompatibilitätsgrenze ändert und ältere native code das Bundle eventuell nicht unterstützen.
Diese Labels sind eine Team-Konvention und kein Weg, native Funktionen via OTA hinzuzufügen. Eine Versionsnummer kann nicht garantieren, dass ein Bundle sicher für eine native App ist. Beziehe echte Kompatibilitätsentscheidungen auf das code und die Abhängigkeiten im Binary.
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 ausliefern wird. Das Hochladen eines korrekt benannten Bundles in einen falschen Channel kann immer noch zu falschen Testergebnissen führen.
Ungültige oder inkonsistente Strings erfordern eine Prüfung statt Raten. Behalte einen bekannten Release-Wert bei, korrigiere die Quelle und teste die aufgelöste Version, bevor du sie promotest.
Die Capgo CLI Befehlsreferenz ist nützlich, wenn du den Upload in ein Skript einbindest, da die Bundle-Version Teil der Inputs des Release-Befehls ist.
Schritt 5: Channel-Eignung vor dem Rollout eines Updates prüfen
Channel-Eignung ist ein Vergleich und kein Raten basierend darauf, welches Bundle neuer aussieht. Capgo prüft das Target-Bundle des Channels gegen die native Baseline, die als version_build. 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.4ist. Wenn ein Channel auf 1.2.5weist, muss das Target mit der nativen Baseline abgeglichen werden, 1.2.3nicht nur mit dem aktuellen 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über der nativen Baseline einschränken. Bei einer major-Strategie kann ein Target mit einer höheren Major-Version blockiert werden. Bei einer minor-Strategie kann ein Target blockiert werden, das die Major- oder Minor-Version der Baseline ändert. Prüfe die konfigurierte Strategie, anstatt davon auszugehen, dass jedes neuere Bundle akzeptiert wird.
Teste die exakte Kombination, die du veröffentlichen willst:
- Installiere den Native Build, der deine Zielgruppe repräsentiert.
- Bestätige die native Baseline, die an Capgo gesendet wurde.
- Ordne das Testgerät dem gewünschten Channel zu.
- Prüfe das Channel-Target und die Version-Strategy.
- Fordere ein Update an und bestätige das Ergebnis auf dem Gerät.
Führe denselben Check auf einer anderen Native Baseline durch, falls deine Userbasis mehrere Store-Versionen nutzt. Ein Bundle, das für einen frischen Build funktioniert, wird bei einer älteren Binary eventuell blockiert – das kann eine beabsichtigte Sicherheitsregel sein.
Starte bei breiteren Releases mit einem Test-Channel oder einem limitierten Rollout. Achte auf unerwartete Ergebnisse bei der Eligibility, bevor du die Zielgruppe erweiterst. Das Channel-Modell von Capgo ermöglicht es Teams, Bundles über Release-Channels zu steuern; halte das Target und die vorgesehene Native Line jedes Channels in deinen Release Notes klar definiert.
Falls sich ein Testgerät nicht aktualisiert, prüfe die Channel-Zuweisung und die Versionswerte, bevor du erneut ein Upload startest. Das wiederholte Veröffentlichen desselben Bundles behebt keinen Baseline-Mismatch.
Schritt 6: Versions-Mismatches diagnostizieren und Releases reproduzierbar machen
Wenn die Werte nicht deinen Erwartungen entsprechen, trace sie der Reihe nach. Bestätige zuerst die Native App Version auf dem Gerät. Prüfe dann, ob ein Configuration Override die Baseline ändert. Vergleiche anschließend die Bundle Version, die Capgo erhalten hat, mit dem Channel Target. Diese Reihenfolge hilft dir zu unterscheiden, ob ein fehlerhafter Source-Wert vorliegt oder ob eine Channel-Regel korrekt arbeitet.
Häufige Ursachen sind das Erhöhen von 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. Notiere genau, welcher Wert nativ ist, welcher das hochgeladene Bundle 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 State 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 dem 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, weshalb es die Prüfung der nativen Baseline und des Target-Bundles des Channels niemals ersetzt.
Wenn du von einem Legacy-Schema migrierst, benenne nicht alle bestehenden Werte in einem Rutsch um. Mappe zuerst die alte native Version auf die native Baseline. Mappe dann das hochgeladene Web-Release auf die Bundle-Version. Teste repräsentative App-Builds gegen die Channel-Strategie, bevor du die 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 reproduzierbar, statt darauf angewiesen zu sein, dass sich jemand an die geänderte Datei erinnert.
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 aktuelle heruntergeladene Bundle-Version ist. Capgo nutzt die native Baseline, wenn es prüft, ob das Target-Bundle eines Channels zulässig ist. Halte die beiden Werte in Logs und Release Notes getrennt, damit du unterscheiden kannst, 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 normalerweise ausfüllt, MARKETING_VERSION. Bei Android stammt die native Version aus defaultConfig.versionName. Eine explizite Updater-Version in der Capacitor Konfiguration kann den gesendeten Wert deiner App ändern; verifiziere daher die gebaute App.
Woher bezieht Capgo die Bundle-Version?
Capgo kann das version -Feld in package.json wenn du keine explizite Bundle-Version angibst. Du kannst die Version auch zusammen mit den CLI angeben. --bundle Wähle eine eindeutige Quelle für deinen Release-Workflow und verifiziere anschließend die Capgo Version, die nach dem Upload empfangen wurde.
Fazit
Nutze version_build für die native Baseline und version_name für das installierte Bundle. Verifiziere vor dem nächsten Rollout beide Werte auf einem Testgerät und vergleiche das Channel-Target mit der Baseline. Dieser eine Check kann Version-Mismatches verhindern, bevor sie eine größere Nutzerbasis erreichen.
