Zum Inhalt springen

Versionzielung

Diese Anleitung erklärt, wie Sie automatisch dem neuesten kompatiblen Bundle an Benutzer liefern können, basierend auf ihrer native App-Version. Ähnlich wie Ionic AppFlows Ansatz.. Dies stellt eine vereinfachte Update-Verwaltung und schnellere Bereitstellungen sicher, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Capgo's Versionsziel-System ermöglicht Ihnen:

  • Automatisch kompatible Updates bereitzustellen benötigten Benutzern auf der Grundlage ihrer native App-Version
  • Verhindern Sie Änderungen, die die Anwendung beschädigen von inkompatiblen App-Versionen
  • Verwalten Sie mehrere App-Versionen gleichzeitig ohne komplexes Logik
  • Erledigen Sie Updates ohne Unterbrechung benötigten Benutzern bestimmte Segmente

Weshalb Version-Zielgruppierung wichtig ist (Besonders für AppFlow-Nutzer)

Sektion mit dem Titel “Weshalb Version-Zielgruppierung wichtig ist (Besonders für AppFlow-Nutzer)”

Wenn Sie mit Ionic AppFlow vertraut sind , wissen Sie, wie wichtig es ist, sicherzustellen, dass Benutzer nur kompatible Updates erhalten. AppFlow matchte automatisch Live-Update-Bundles mit native App-Versionen, um inkompatibles JavaScript von älteren native __CAPGO_KEEP_0__ zu verhindern., you know how critical it is to ensure users receive only compatible updates. AppFlow automatically matched live update bundles to native app versions, preventing incompatible JavaScript from being delivered to older native code.

Capgo bietet die gleichen Sicherheitsgarantien, mit zusätzlichen Funktionen:

  • Feinere Kontrolle über die Versionsübereinstimmung
  • Mehrfache Strategien (Kanäle, semver, native Einschränkungen)
  • Bessere Sichtbarkeit in die Versionsverteilung
  • API und CLI steuern neben der Dashboard-Verwaltung

Diese Vorgehensweise ist insbesondere nützlich, wenn:

  • Sie haben Benutzer auf verschiedenen Hauptversionen Ihrer App (z.B. v1.x, v2.x, v3.x)
  • Sie müssen die rückwärtskompatiblen Änderungen aufrechterhalten, während Sie die unterbrechenden Änderungen einführen
  • Sie möchten verhindern, dass neue Pakete ältere native code beschädigen
  • Sie migrieren die Benutzer allmählich von einer Version zur anderen
  • Sie migrieren von AppFlow und möchte die gleiche Update-Sicherheit aufrechterhalten

Capgo verwendet eine mehrschichtige Ansicht, um Benutzer mit kompatiblen Updates zu verbinden:

  1. Native Version Constraints: Verhindert, dass Pakete an inkompatiblen native Versionen geliefert werden
  2. Channel-Based Routing: Routet verschiedene App-Versionen zu verschiedenen Update-Kanälen
  3. Semantic Versioning Controls: Blockiert automatisch Updates über Major-/Minor- bzw. Patch-Grenzen
  4. Device-Level Overrides: Zieht spezifische Geräte oder Benutzergruppen ins Visier
graph TD
A[User Opens App] --> B{Check Device Override}
B -->|Override Set| C[Use Override Channel]
B -->|No Override| D{Check local plugin channel}
D -->|setChannel value| E[Use local setChannel channel]
D -->|No local channel| F{Check defaultChannel in App}
F -->|Has defaultChannel| G[Use App's defaultChannel]
F -->|No defaultChannel| H[Use Cloud Default Channel]
C --> I{Check Version Constraints}
E --> I
G --> I
H --> I
I -->|Compatible| J[Deliver Update]
I -->|Incompatible| K[Skip Update]

Dies ist die empfohlene Vorgehensweise für die Verwaltung von Bruchänderungen und wichtigen Versionsupdates. Sie ähnelt dem Liefermodell von AppFlow.

  • App v1.x (100.000 Benutzer) → production Kanal
  • App v2.x (50.000 Benutzer mit Änderungen, die den Betrieb beeinträchtigen) → v2 Kanal
  • App v3.x (10.000 Beta-Benutzer) → v3 Kanal
// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production', // or omit for default
}
}
};
export default config;
// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // Routes v2 users automatically
}
}
};
// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v3', // Routes v3 users automatically
}
}
};
Terminalfenster
# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3
# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign
Terminalfenster
# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production
# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2
# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3
  • Zero code changes Keine __CAPGO_KEEP_0__-Änderungen
  • - Der Kanalrouting erfolgt automatisch - Jede Version hat ihren eigenen Update-Pipeline
  • - Flexible Zielsetzung - Push-Updates an bestimmte Versionen senden
  • - Sichere Rollouts - Bruchstellen ändern nie inkompatible Versionen

Strategie 2: Kontrolle über semantische Versionen

Überschrift: ‘Strategie 2: Kontrolle über semantische Versionen’

Verwenden Sie Capgo’s eingebauten semantische Versionskontrolle um Updates über Versionsgrenzen zu verhindern.

Automatische Updates über Hauptversionen deaktivieren

Überschrift: ‘Automatische Updates über Hauptversionen deaktivieren’
Terminalfenster
# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

Diese Konfiguration bedeutet:

  • Benutzer mit der App-Version 1.2.3 werden Updates bis zu 1.9.9
  • Benutzer erhalten NICHT keine Version 2.0.0 automatisch
  • Verhindert, dass bruchiale Änderungen älteren native code
  • Die Vergleichung verwendet die native Basislinie, die als version_build
Terminalfenster
# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor
# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch
# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Legen Sie eine Mindestversion des native Apps (min_update_version) auf jedem Bundle fest, damit Capgo nur an Geräten mit einer neuen genügend großen native Binärdatei geliefert wird.

Dies verwendet die Kanal Metadaten--disable-auto-update metadataStrategie ( --min-update-version oder --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Abschnitt: Enable metadata targeting auf dem Kanal

Terminalfenster
Zur Zwischenablage kopieren
# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Abschnitt: Setzen Sie eine Mindestversion für native Apps auf Upload

Wenn Sie ein Bundle hochladen, geben Sie die niedrigste native Version an, die es empfangen kann:

Terminalfenster

Zur Zwischenablage kopieren
# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "2.0.0"

Oder lassen Sie Capgo die Grenze von der nativen Paketkompatibilität setzen:

Terminalfenster
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version
  1. Neuer Native-Plugin erforderlich

    Terminal-Fenster
    # Bundle needs Camera plugin added in v2.0.0
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "2.0.0"
  2. Kritische Native API-Änderungen

    Terminal-Fenster
    # Bundle uses new Capacitor 6 APIs
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "3.0.0"
  3. Schrittweiser Umstieg

    Terminal-Fenster
    # one-time: enable metadata gating on beta
    npx @capgo/cli@latest channel set beta --disable-auto-update metadata
    # Test bundle only on latest native version
    npx @capgo/cli@latest bundle upload \
    --channel beta \
    --min-update-version "2.5.0"

Verhindere, dass Benutzer Pakete erhalten, die älter sind als ihre aktuelle native Version.

Im Capgo-Dashboard:

  1. Gehe zu Kanäle Kanal
  2. → Wähle deinen Kanal Enable
  3. “Deaktiviere automatische Downgrade unter native”

Or via CLI:

Oder über __CAPGO_KEEP_0__:
npx @capgo/cli@latest channel set production --no-downgrade
  • Geräte des Benutzers: Native Version 1.2.5
  • Kanal-Paket: Version 1.2.3
  • Ergebnis: Aktualisierung wird blockiert (würde eine Downgrade darstellen)

Dies ist nützlich, wenn:

  • Benutzer haben eine neuere Version manuell aus dem App-Store installiert
  • Sie sicherstellen müssen, dass Benutzer immer die neuesten Sicherheitspatches erhalten
  • Sie möchten Regressionsfehler verhindern

Strategie 5: Gerätebasierte Zielgruppenabgrenzung

Abschnitt mit dem Titel “Strategie 5: Geräteebene Zielsetzung”

Überschreiben Sie die Kanalzuweisung für bestimmte Geräte oder Benutzergruppen.

import { CapacitorUpdater } from '@capgo/capacitor-updater'
// Force beta testers to use v3 channel
async function assignBetaTesters() {
const deviceId = await CapacitorUpdater.getDeviceId()
// Check if user is beta tester
if (isBetaTester(userId)) {
await CapacitorUpdater.setChannel({ channel: 'v3' })
}
}

In der Capgo-Übersicht:

  1. Gehe zu Geräte → Gerät finden
  2. Klicken Set Kanal oder Set Version
  3. Überschreiben mit spezifischem Kanal- oder Bundle-Version
  4. Das Gerät erhält Updates aus dem überschriebenen Quellcode

Hier ist ein vollständiges Beispiel, das alle Strategien kombiniert:

Terminalfenster
# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
--disable-auto-update metadata \
--no-downgrade
capacitor.config.ts
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production',
}
}
};
Terminalfenster
# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
--disable-auto-update metadata \
--no-downgrade \
--self-assign
# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance
// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // New users get v2 channel
}
}
};
Terminalfenster
# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "1.0.0"
# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
--channel v2 \
--min-update-version "2.0.0"

4. Versionsverteilung überwachen

Abschnitt "4. Versionsverteilung überwachen"

Verwende das Capgo-Dashboard, um zu überwachen:

  • Wie viele Benutzer sind auf v1 gegenüber v2
  • Zuordnungsrate pro Version
  • Fehler oder Abstürze pro Version

5. Veraltete Version deaktivieren

Abschnitt "5. Veraltete Version deaktivieren"

Wenn die v1-Nutzung unter der Schwellenwert fällt:

Terminalfenster
# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance
# Move all remaining users to default
# (They'll need to update via app store)

Wenn mehrere Kanalkonfigurationen existieren, verwendet Capgo diese Vorrangreihenfolge:

  1. Geräteüberschreibung (Dashboard oder API) - Höchster Priorität und sichtbar in der Geräteüberschreibungs-UI
  2. Lokaler Pluginkanal via setChannel() - Auf dem Gerät nur gespeichert und nicht in der Geräteüberschreibungs-UI angezeigt
  3. defaultChannel in capacitor.config.ts
  4. Standardkanal (Cloudflare-Einstellung) - Niedrigste Priorität

1. Stellen Sie immer die Standardkanal-Einstellung für Hauptversionen ein

Abschnitt mit dem Titel „1. Setze immer defaultChannel für große Versionen“
// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3
// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually
Terminal-Fenster
# ✅ Good
1.0.0 1.0.1 1.1.0 2.0.0
# ❌ Bad
1.0 1.1 2 2.5
Terminal-Fenster
# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions
Terminalfenster
# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel first
npx @capgo/cli@latest bundle upload \
--channel beta \
--auto-min-update-version
# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version

Überprüfen Sie regelmäßig Ihr Dashboard:

  • Stellen Benutzer eine Upgrade auf neueren native Versionen vor?
  • Bekommen alte Versionen noch viel Traffic?
  • Sollten Sie alte Kanäle deprecieren?

Für Teams, die von Ionic AppFlow migrieren Ionic AppFlow, hier ist der Vergleich von Capgo’s Version-Zielgruppierung:

FeatureIonischer AppFlowCapgo
Version-basierte RoutenführungAutomatisch basierend auf nativer VersionAutomatisch über defaultChannel + mehrere Strategien
Semantische VersionsnummerGrundlegende UnterstützungErweitert mit --disable-auto-update (Major/Minor/Patch)
Native Version EinschränkungenManuelle Konfiguration im AppFlow-DashboardIntegriert --min-update-version / --auto-min-update-version mit Metadatenkanälen
KanalverwaltungWeb-UI + CLIWeb-UI + CLI + API
GeräteüberschreibungenEingeschränkte GeräteeinflussnahmeVollständige Kontrolle über das Dashboard/API
Verhinderung von DowngradenJaJa über --no-downgrade
Multi-Version-WartungManuelle Verwaltung von Branchen/CanälenAutomatisiert mit Vorrang vor dem Kanal
SelbsthostingNeinJa (vollständige Kontrolle)
Versionen-AnalyseGrundlegendDetaillierte pro-Version-Metriken

Überprüfen Sie Folgendes:

  1. Kanalzuweisung: Überprüfen Sie, ob das Gerät auf dem richtigen Kanal ist

    const channel = await CapacitorUpdater.getChannel()
    console.log('Current channel:', channel)
  2. Versionsbeschränkungen: Überprüfen Sie, ob das Bundle native Versionen anfordert

    • Dashboard → Bundles → Überprüfen Sie die Spalte „Native Version“
  3. Semver-Einstellungen: Überprüfen Sie die des Kanals disable-auto-update Einstellung

    Terminalfenster
    npx @capgo/cli channel list
  4. Geräteüberschreibung: Überprüfen Sie, ob das Gerät eine manuelle Überschreibung hat

    • Dashboard → Geräte → Gerät suchen → Kanal/Versionsnummer überprüfen
  1. Überprüfen Sie die Standardkanal: Stellen Sie sicher, dass der richtige Kanal in capacitor.config.ts
  2. Überprüfen Sie die Bundle-Uploads: Überprüfen Sie, ob die Bundle auf den beabsichtigten Kanal hochgeladen wurde
  3. Überprüfen Sie die Mindestaktualisierungsversion: Bestätigen Sie --min-update-version (oder --auto-min-update-version) wurde festgelegt und der Kanal verwendet --disable-auto-update metadata
  1. Eilmaßnahme: Aktivieren Sie die betroffenen Geräte auf die sichere Bundle
    • Zentrale Oberfläche → Geräte → Masseauswahl → Versionsnummer setzen
  2. Langfristige Korrektur: Erstellen Sie kanalisierte Versionen und pflegen Sie separate Zweige
  3. Prävention: Testen Sie Updates immer auf repräsentativen Geräten vor der Ausrollung

Wenn Sie von Ionic AppFlow migrieren Ionic AppFlow, funktioniert die Versionszielelementierung ähnlich in Capgo, mit verbessertem Flexibilität:

AppFlow KonzeptCapgo ÄquivalentHinweise
Deploy-KanalCapgo KanalSelbst gleicher Konzept, aber mächtiger
Native Version-Sperre--min-update-version / --auto-min-update-versionMehr feinere Kontrolle
Kanal-PrioritätKanal-Vorrang (Übergeordnet → Cloud → Standard)Mehr transparenter Vorrang
Zielsystem für die BereitstellungKanal + semver-KontrolMehrere Strategien verfügbar
Produktionskanalproduction Kanal (oder beliebiger Name)Flexible Namensgebung
Git-basierte BereitstellungCLI Bundle-Upload aus der BranchSelbe Workflow
Automatische VersionszuordnungdefaultChannel + VersionsbeschränkungenVerbessert mit mehreren Strategien
  1. Mehr Kontrolle: Capgo bietet Ihnen mehrere Strategien (Kanäle, semver, native Version) die kombiniert werden können
  2. Bessere Sichtbarkeit: Das Dashboard zeigt die Versionsverteilung und Kompatibilitätsprobleme
  3. API Zugriff: Vollständige programmatische Kontrolle über die Versionszieleinstellungen
  4. Selbst-Hosting: Option zum Betreiben Ihres eigenen Update-Servers mit gleicher Versionslogik
  1. Ihre AppFlow-Kanäle zuordnen zu Capgo Kanälen (üblicherweise 1:1)
  2. Setzen defaultChannel in capacitor.config.ts für jede Hauptversion
  3. Konfigurieren Sie semver-Regeln wenn Sie eine automatische Blockierung an Versionsgrenzen wünschen
  4. Hochladen von Versionsspezifischen Paketen mit --min-update-version (Der Kanal muss die Metadatenstrategie verwenden)
  5. Überwachen der Versionsverteilung in Capgo Dashboard
// Gradually migrate v1 users to v2
async function migrateUsers() {
const deviceId = await CapacitorUpdater.getDeviceId()
const rolloutPercentage = 10 // Start with 10%
// Hash device ID to get deterministic percentage
const hash = hashCode(deviceId) % 100
if (hash < rolloutPercentage) {
// User is in rollout group - migrate to v2
await CapacitorUpdater.setChannel({ channel: 'v2' })
}
}
// Enable features based on native version
async function checkFeatureAvailability() {
const info = await CapacitorUpdater.getDeviceId()
const nativeVersion = info.nativeVersion
if (compareVersions(nativeVersion, '2.0.0') >= 0) {
// Enable features requiring v2.0.0+
enableNewCameraFeature()
}
}

A/B-Testung über Versionen

A/B-Testung über Versionen
// Run A/B tests within same native version
async function assignABTest() {
const nativeVersion = await getNativeVersion()
if (nativeVersion.startsWith('2.')) {
// Only A/B test on v2 users
const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
await CapacitorUpdater.setChannel({ channel: variant })
}
}

Capgo bietet mehrere Strategien für die versionsspezifische Lieferung von Updates:

  1. Kanalbasierte Routing: Automatische Versionsunterscheidung via defaultChannel
  2. Semantische Versionsnummer: Verhindere Updates über Major/Minor/Patch-Grenzen
  3. Nativversionenbeschränkungen: Erforderliche Mindestnativversion für Bundles
  4. Verhinderung der automatischen Downgrade: Nie liefern Sie ältere Pakete an neueren native Versionen
  5. Geräteüberschreibungen: Manueller Kontrolle für Tests und Zielsetzung

Indem Sie diese Strategien kombinieren, können Sie eine AppFlow-ähnliche automatische Aktualisierungsbereitstellung mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die geeignete Ansatz, der Ihren Anwendungsversionierung und -bereitstellung Workflow am besten entspricht.

Weitere Informationen zu bestimmten Funktionen:

Wenn Sie Version-Zielsetzung verwenden Version-Zielsetzung zum Planen der Kanalroutings und der schrittweisen Veröffentlichung, verbinden Sie es mit Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle Zielgruppen-Testlösung zum Produktworkflow in Zielgruppen-Testlösung und zum Produktworkflow in Zielgruppen-Testlösung und zum Produktworkflow in Zielgruppen-Testlösung und Versionziel-Lösung für das Produktworkflow in Versionziel-Lösung.