Zum Inhalt springen

Versionsziel

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 Rollouts 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-Zielsetzung wichtig ist (Besonders für AppFlow-Nutzer)

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

Wenn Sie sich mit Ionic AppFlow vertraut gemacht haben , 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

Dieser Ansatz 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 durchbrechenden Ä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 inkompatible 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/Major- und 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 zur Verwaltung von Bruchlinienä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
}
}
};
Terminal-Fenster
# 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
Terminal-Fenster
# 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 Änderungen
  • - Der Kanalrouting erfolgt automatisch Klare Trennung
  • - Jede Version hat ihren eigenen Update-Pipeline Flexible Zielgruppen
  • - Push-Updates an bestimmte Versionengruppen senden Sichere Rollouts

Verwenden Sie Capgos eingebettete semantische Versionskontrollen um Updates über Versionsgrenzen hinweg zu verhindern.

Terminal-Fenster
# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

Dieses Konfigurationswert 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 erreichen
  • 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 ausgeliefert wird, deren native Binärdatei neu genug ist.

Dies verwendet die Kanal Metadaten Strategie (--disable-auto-update metadata) plus --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 Mindestversion von der nativen Paketkompatibilität bestimmen:

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. Schrittweise Migration

    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 Kanäle
  2. → Wähle deinen Kanal Ermögliche
  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 Regression-Bugs verhindern möchten

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.

Zwingende Spezifische Version für Tests

Zum Clipboard kopieren
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' })
}
}

Abschnitt mit dem Titel “Dashboard Geräteüberschreibung”

Im __CAPGO_KEEP_0__ Dashboard:

In the Capgo dashboard:

  1. Geräte → Gerät finden Klicken
  2. Abschnitt mit dem Titel “Zwingende Spezifische Version für Tests” Kanal festlegen oder Entscheiden Sie, ob Sie eine bestimmte Kanal- oder Paketversion verwenden möchten
  3. Der Gerät erhält Updates aus der überschriebenen Quelle
  4. Testaktualisierungen

Abschnitt mit dem Titel „Vollständiger AppFlow-Workflow“

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

1. Initialisierung (App v1.0.0)

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

Verwenden Sie das Capgo-Dashboard, um zu überwachen:

  • Wie viele Benutzer sind auf v1 gegenüber v2
  • Zuordnungen 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ätsstufe 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 Standardkanäle für Hauptversionen fest

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

5. Versionsverteilung überwachen

Abschnitt "5. Versionsverteilung überwachen"

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

  • Stellen Benutzer auf neueren nativen Versionen um?
  • Bekommen alte Versionen noch viel Traffic?
  • Sollten Sie alte Kanäle deprecieren?

Vergleich mit Ionic AppFlow

Abschnitt "Vergleich mit Ionic AppFlow"

Für Teams, die von Ionic AppFlow migrieren Ionic AppFlow, hier ist ein Vergleich der Versionierung von Capgo:

FunktionIonic AppFlowCapgo
Version-basierte RoutenführungAutomatisch basierend auf der nativen VersionAutomatisch über defaultChannel + mehrere Strategien
Semantische VersionierungGrundlegende UnterstützungErweitert mit --disable-auto-update (Major/Minor/Patch)
Native VersionsbeschränkungenManuelle Konfiguration im AppFlow-DashboardEingebaut --min-update-version / --auto-min-update-version mit Metadatenkanälen
KanalverwaltungWeb-UI + CLIWeb-UI + CLI + API
GeräteüberschreibungenEingeschränkte Geräteebene-KontrolleVollständige Kontrolle über Dashboard/API
Verhinderung von DowngradesJaJa über --no-downgrade
Multi-Version-WartungManuelle Verwaltung von Branchen/CanälenAutomatisiert mit Vorrang von Canälen
SelbstbetriebNeinJa (voller Kontrolle)
Versionen-AnalyseGrundlegendDetaillierte Metriken pro Version

Abschnitt mit dem Titel "Fehlerbehebung"

Benutzer erhalten keine Updates

Abschnitt mit dem Titel "Benutzer erhalten keine Updates"

Überprüfen Sie Folgendes:

Kanalzuweisung

  1. : Überprüfen Sie, ob das Gerät auf dem richtigen Kanal istAuf die Zwischenablage kopieren

    const channel = await CapacitorUpdater.getChannel()
    console.log('Current channel:', channel)
  2. __CAPGO_KEEP_0__ provides: Prüfen, ob das Bundle native Versionen anfordert

    • Zurück zur Oberfläche → Bundles → Überprüfen Sie die Spalte "Native Version"
  3. Semver-Einstellungen: Überprüfen Sie die 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

    • Zurück zur Oberfläche → Geräte → Gerät suchen → Überprüfen Sie die Kanal-Version
  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 Mindestupdateversion: Bestätigen Sie --min-update-version (oder --auto-min-update-version) wurde gesetzt und der Kanal verwendet --disable-auto-update metadata
  1. Unmittelbare Korrektur: Aktivieren Sie die betroffenen Geräte auf die sichere Bundle umzustellen
    • Zurück zum Dashboard → Geräte → Masseauswahl → Versionsnummer setzen
  2. Langefristige 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 AppFlowzum Capgo migrieren, funktioniert die Versionszielsetzung ähnlich, aber mit verbesserter Flexibilität:

AppFlow KonzeptCapgo ÄquivalentHinweise
Veröffentlichungs-KanalCapgo KanalSelbiges Konzept, aber mächtiger
Native Version-Sperre--min-update-version / --auto-min-update-versionMehr fein abgestimmte Kontrolle
Kanal-PrioritätKanal-Vorrang (Übergeordnet → Cloud → Standard)Mehr transparenter Vorrang
Zielsystem für die BereitstellungKanal + semver-KontrollenVerfügbare Strategien
Produktionskanalproduction Kanal (oder beliebiger Name)Flexible Namensgebung
Git-basierte BereitstellungCLI Bundle-Upload aus der BranchSelbe Workflow
Automatische VersionszuordnungdefaultChannel + VersionsbeschränkungenErweitert 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 Versionszieleinstellung
  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 Versionsabhängige Aktualisierungsübermittlung:

  1. Kanalbasierte Routing: Automatische Versionsunterscheidung via defaultChannel
  2. Semantische Versionsnummer: Verhindere Aktualisierungen über Haupt-/Minder-/Patchgrenzen
  3. Nativversionen Einschränkungen: Erforderliche Mindestnativversion für Bundles
  4. Verhinderung der automatischen Downgrade: Nie liefern ältere Pakete an neueren native Versionen
  5. Geräte-Überschreibungen: Manuelle Kontrolle für Tests und Zielsetzungen

Indem Sie diese Strategien kombinieren, können Sie AppFlow-ähnliche automatische Update-Lieferungen mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die geeignete Methode, die Ihren Anwendungs-versions- und -veröffentlichungsworkflow am besten passt.

Für weitere Details zu bestimmten Funktionen:

Wenn Sie Version-Zielsetzung verwenden Version-Zielsetzung zum Planen von Kanalrouting und einer gestuften Veröffentlichung, verbinden Sie es mit Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle Betatestlösung zum Produktworkflow in Betatestlösung und zum Produktworkflow in Betatestlösung und Versionziel-Lösung Versionziel-Lösung für das Produktworkflow.