Version-Ziel

Diese Anleitung erklärt, wie Sie automatisch dem Benutzer die neueste kompatible Bundle liefern können, basierend auf ihrer nativen App-Version, ähnlich wie bei Ionic AppFlow’s Ansatz. Dies stellt eine vereinfachte Update-Verwaltung und schnellere Rollouts sicher, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Von Ionic AppFlow migrieren?

Wenn Sie aus Ionic AppFlow kommen, ist diese Anleitung besonders wichtig für Sie. AppFlow matchte automatisch Updates mit nativen Versionen ab, und Capgo bietet dieselbe Funktion mit noch mehr Kontrolle und Flexibilität. Siehe die AppFlow-Migration-Anleitung für Schritt-für-Schritt-Anweisungen zur Migration.

Übersicht

Capgo’s Versionsziel-System ermöglicht Ihnen:

• Automatisch kompatible Updates an Benutzer liefern basierend auf ihrer native App-Version
• Verhindern, dass veraltete Änderungen an inkompatible App-Versionen gelangen
• Mehrfach-App-Versionen ohne komplexes Logik simultan ohne Verwirrung verwalten
• Updates an bestimmten Benutzergruppen warum Versionsziel-System wichtig ist (insbesondere für AppFlow-Nutzer)

Überschrift: warum Versionsziel-System wichtig ist (insbesondere für AppFlow-Nutzer)

Wenn Sie sich mit dem Versionsziel-System vertraut gemacht haben Ionic AppFlowSie wissen, wie wichtig es ist, sicherzustellen, dass Benutzer nur kompatible Updates erhalten. AppFlow matchte automatisch Live-Update-Bundles mit native App-Versionen ab, um inkompatible JavaScript von älteren native code zu verhindern.

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

• Feinere Kontrolle über die Versionsabstimmung
• Mehrere Strategien (Kanäle, semver, native Einschränkungen)
• Bessere Sichtbarkeit in die Versionsverteilung
• API und CLI steuern neben Dashboard-Management

Diese Vorgehensweise ist insbesondere dann 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ärtskompatible Kompatibilität aufrechterhalten, während Sie Bruchteile ändern
• Sie möchten verhindern, dass neue Pakete ältere native code beschädigen
• Sie migrieren die Benutzer allmählich von einer Version zu einer anderen
• Sie migrieren von AppFlow und möchten die gleiche Sicherheit bei Updates aufrechterhalten

Wie es funktioniert

Capgo verwendet einen mehrschichtigen Ansatz, um Benutzer mit kompatiblen Updates zu verbinden:

1. Native Version Constraints: Verhindern Sie, dass Bundles an inkompatible native Versionen geliefert werden
2. Channel-Based Routing: Leiten Sie verschiedene App-Versionen an verschiedene Update-Kanäle weiter
3. Semantic Versioning Controls: Blockieren Sie automatisch Updates über Major/Major/Minor-Grenzen
4. Geräte-Ebene Überschreibungen: Ziel spezifische Geräte oder Benutzergruppen

Versionenabgleich-Fluss

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]

Strategie 1: Channel-basierte Versionsrouting

Dies ist die empfohlene Vorgehensweise zur Verwaltung von Bruchänderungen und großen Versionsupdates. Es ähnelt dem Liefermodell von AppFlow.

Beispiel-Szenario

• App v1.x (100.000 Benutzer) → production Kanal
• App v2.x (50.000 Benutzer mit Bruchlinienänderungen) → v2 Kanal
• App v3.x (10.000 Beta-Benutzer) → v3 Kanal

Implementierung

Schritt 1: Konfigurieren Sie Kanäle für jede Hauptversion

// 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
    }
  }
};

Schritt 2: Erstellen Sie Kanäle

# 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

Schritt 3: Hochladen von Versionsspezifischen Paketen

# 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

Automatische Routing

Wenn Benutzer die App öffnen, verbinden sie sich automatisch mit ihrem zugeordneten Kanal basierend auf dem defaultChannel in ihrem installierten App-Bundle. Keine JavaScript code-Änderungen erforderlich!

Vorteile

• Null code-Änderungen - Die Kanalroutings erfolgen automatisch
• Klare Trennung - Jede Version hat ihren eigenen Update-Pipeline
• Flexibles Zielsetzen - Push-Updates an bestimmte Versionengruppen senden
• Sichere Rollouts - Änderungen, die die Kompatibilität gefährden, erreichen keine inkompatiblen Versionen

Strategie 2: Kontrolle über semantische Versionen

Nutzen Sie Capgos eingebaute semantische Versionskontrolle um Updates über Versionsgrenzen zu verhindern.

Automatische Updates über Hauptversionen deaktivieren

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

Diese Konfiguration bedeutet:

• Benutzer auf der App-Version 1.2.3 werden Updates bis zu 1.9.9
• Benutzer werden NICHT die Version 2.0.0 automatisch
• Verhindert, dass sich verändernde Änderungen auf ältere native code auswirken
• Der Vergleich verwendet die native Basis, die als version_build

Feinste Kontrollmöglichkeiten

# 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

Semantic Versioning erforderlich

Diese Strategie funktioniert nur, wenn Sie semantische Versionsnummerierung (semver) für Ihre App-Versionen einhalten. Stellen Sie sicher, dass Ihre Versionsnummern der MAJOR.MINOR.PATCH Format folgen.

Strategie 3: Native Version Constraints

Legen Sie die Mindestanforderungen an die native Version für Bundles fest, um die Lieferung an inkompatible Geräte zu verhindern.

Verwendung von nativeVersion Delay Condition

Wenn Sie ein Bundle hochladen, können Sie eine Mindestanforderung an die native Version angeben:

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

Wie es funktioniert

Geräte auf der native Version 1.x erhalten diese Pakete NICHT. Nur Geräte auf 2.0.0+ erhalten sie. Dies ist perfekt für Updates, die neue native APIs oder Plugins erfordern.

Verwendungsfälle

1. Neuer Native-Plugin erforderlich

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. Abbruch von Native API Änderungen

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. Schrittweise Migration

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

Strategie 4: Verhindern von automatischen Downgrades

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

Aktivieren Sie in den Kanal-Einstellungen

In der Capgo-Oberfläche:

1. Gehe zu Kanäle → Deinen Kanal auswählen
2. Aktivieren “Automatische Downgrade unter nativ deaktivieren”
3. Änderungen speichern

Oder via CLI:

npx @capgo/cli channel set production --disable-downgrade

Beispiel

• Gerät des Benutzers: Nativversion 1.2.5
• Kanalbundle: Version 1.2.3
• Ergebnis: Aktualisierung wird blockiert (würde zu einer Downgrade führen)

Dies ist nützlich, wenn:

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

Strategie 5: Geräteebene Zielsetzung

Überschreiben der Kanalzuweisung für bestimmte Geräte oder Benutzergruppen

Zwingen einer bestimmten Version für die Testung

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' })
  }
}

Übersicht Geräteüberschreibung

In der Capgo-Übersichtsseite:

1. Gehe zu Geräte → Gerät finden
2. Klicken Kanal setzen oder Version setzen
3. Überschreiben mit spezifischem Kanal oder Paketversion
4. Das Gerät erhält Updates von der überschriebenen Quelle

Updates testen

Verwenden Sie Geräte-Überschreibungen, um Updates auf Ihrem eigenen Gerät zu testen, bevor Sie sie allen Benutzern bereitstellen.

Vollständiger AppFlow-Style Workflow

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

1. Initial Setup (App v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. Release Breaking Change (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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
    }
  }
};

3. Push Updates zu Beiden Versionen

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. Überwachen Sie die Versionenverteilung

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

• Wie viele Benutzer sind auf v1 vs v2 unterwegs
• Verbreitungsraten pro Version
• Fehler oder Abstürze pro Version

5. Veraltetes Version deaktivieren

Wenn die Verwendung von v1 unter der Schwellenwert fällt:

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

Kanalvorrang

Wenn mehrere Kanalkonfigurationen existieren, verwendet Capgo folgende Vorrangfolge:

1. Geräteüberschreibung (Dashboard oder API) - Höchster Vorrang und sichtbar in der Geräteüberschreibung-UI
2. Lokale Plugin-Kanal via setChannel() - Auf dem Gerät gespeichert und nicht im Geräte-Überschreibungs-UI angezeigt
3. Standardkanal in capacitor.config.ts
4. Standardkanal (Cloud-Einstellung) - Niedrigste Priorität

Vorrangbeispiel

Wenn eine App eines Benutzers defaultChannel: 'v2' aber Sie überschreiben ihren Gerät zu 'beta' im Dashboard, erhalten sie Updates von der 'beta' Kanal.

Die Geräte-Überschreibungs-Oberfläche listet nur Überschreibungen auf, die vom Dashboard oder öffentlichen API gesetzt wurden. Aufrufe setChannel() Von der App validiert der Kanal mit dem Backend, dann wird er lokal auf dem Gerät gespeichert.

Gute Praktiken

1. Stellen Sie immer defaultChannel für große Versionen fest

// ✅ 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

2. Verwenden Sie semantische Versionsnummern

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Getrennte Branchen aufrechterhalten

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. Testen Sie vor der Veröffentlichung

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. Überwachen Sie die Versionsverteilung

Stellen sich die Benutzer auf neueren nativen Versionen um?

• Zur Zwischenablage kopieren
• Bekommen alte Versionen noch viel Traffic?
• Sollten Sie alte Kanäle deaktivieren?

Vergleich mit Ionic AppFlow

Für Teams, die von Ionic AppFlowhier ist, wie Capgo’s Version-Zielvergleich funktioniert:

Funktion	Ionic AppFlow	Capgo
Version-basierte Routing	Automatisches basierend auf nativer Version	Automatische via defaultChannel + mehrere Strategien
Semantische Versionsnummer	Grundlegende Unterstützung	Erweitert mit --disable-auto-update (Major/Minor/Patch)
Native Versionenbeschränkungen	Manuelle Konfiguration in AppFlow-Dashboard	Eingebaut --native-version Flag in CLI
Kanalverwaltung	Web-UI + CLI	Web UI + CLI + API
Geräte-Überschreibungen	Eingeschränkte Geräte-Einstellungen	Vollständige Kontrolle über der Dashboard/API
Verhinderung von automatischen Downgrades	Ja	Ja über --disable-downgrade
Unterhaltung mehrerer Versionen	Manuelle Verwaltung von Branchen/Kanälen	Automatisiert mit Vorzug von Kanälen
Selbst-Hosting	Nein	Ja (vollständige Kontrolle)
Version-Analytik	Grundlegend	Detaillierte pro-Version-Metriken

AppFlow Parität und Jenseits

Capgo bietet alle Versionenziel-Fähigkeiten die AppFlow bot, plus zusätzliche Kontrollmechanismen. Wenn Sie sich auf AppFlows automatische Versionszuweisung verlassen haben, finden Sie Capgo genauso sicher, aber mit mehr Flexibilität.

Fehlersuche

Benutzer erhalten keine Updates

Ü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. Versionenbeschrä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 Einstellung des Kanals disable-auto-update Terminal-Fenster

   npx @capgo/cli channel list

4. Geräteumstellung: Überprüfen Sie, ob das Gerät eine manuelle Umstellung hat

   • Zur Dashboard-Seite → Geräte → Gerät suchen → Kanal-Version überprüfen

Bundle wurde an falsche Version geliefert

1. Standardkanal überprüfen: Stellen Sie sicher, dass der richtige Kanal in capacitor.config.ts
2. Bundle hochladen überprüfen: Bestätigen Sie, dass das Bundle an den richtigen Kanal hochgeladen wurde
3. Natives Version überprüfen: Bestätigen Sie, dass die richtige Version --native-version Flag wurde korrekt verwendet

Änderungen, die alte Versionen betreffen

1. Eilmaßnahme: Betroffene Geräte auf sicheren Bundle umstellen
   • Dashboard → Geräte → Masseauswahl → Version setzen
2. Langfristige Lösung: Versionierte Kanäle erstellen und separate Branches pflegen
3. Vorbeugung: Alle Updates auf repräsentativen Geräten vor der Rollout testen

Migration von Ionic AppFlow

If Sie von Ionic AppFlow migrieren, funktioniert die Versionsziele-Unterstützung in __CAPGO_KEEP_0__ sehr ähnlich, mit verbessertem Flexibilität: Konzeptabbildung, version targeting works very similarly in Capgo, with improved flexibility:

AppFlow-Konzept

Hinweise	Capgo Equivalent	__CAPGO_KEEP_0__-Kanal
Das gleiche Konzept, aber mächtiger	Capgo Channel	Same concept, more powerful
Native Version Lock	--native-version Flag	Mehr granulare Kontrolle
Kanalpriorität	Kanalvorrang (Überschreiben → Cloud → Standard)	Mehr transparenter Vorrang
Zielsystem für die Bereitstellung	Kanal + semver-Kontrollen	Mehrere Strategien verfügbar
Produktionskanal	production Kanal (oder beliebiger Name)	Flexible Namensgebung
Git-basierte Bereitstellung	CLI Paket-Upload aus der Branch	Selbe Workflow
Automatische Versionsabgleich	defaultChannel + Versionsbeschränkungen	Verbessert mit mehreren Strategien

Schlüsselunterschiede für AppFlow-Nutzer

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 an
3. API Zugriff: Vollständige programmatische Kontrolle über Versionsziele
4. Selbst-Hosting: Option, eigene Update-Server mit gleicher Versionslogik zu betreiben

Migrationsschritte

1. Deine AppFlow-Kanäle zu Capgo Kanälen (üblicherweise 1:1)
2. Setzen defaultChannel bei capacitor.config.ts für jede Hauptversion
3. Konfigurieren von semver-Regeln falls automatische Blockierung an Versionsgrenzen gewünscht ist
4. Versionsspezifische Pakete hochladen mit --native-version Flagge
5. Versionenverteilung überwachen in Capgo-Dashboard

Migrationsanleitung abschließen

Für eine vollständige Migrationsanleitung einschließlich SDK-Ersatz und API-Mapping, siehe die AppFlow zu Capgo-Migrationsanleitung.

Erweiterte Muster

Schrittweise Umstellung nach Version

// 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' })
  }
}

Feature-Flags durch Version

// 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 hinweg

// 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 })
  }
}

Zusammenfassung

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

1. Kanalbasierte Routensteuerung: Automatische Versionsunterscheidung über defaultChannel
2. Semantic Versioning: Verhindere Updates über Haupt-/Minor- und Patcheschwellen
3. Native Version Constraints: Erforderliche Mindestversion für native Bundles
4. Auto-Downgrade Prevention: Liefer nie ältere Bundles an neuere native Versionen
5. Device Overrides: Manuelle Kontrolle für Testen und Zielsetzen

Indem Sie diese Strategien kombinieren, können Sie AppFlow-Style-Updates mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die geeignete Vorgehensweise, die am besten zu Ihrem Apps Versions- und Bereitstellungsworkflow passt.

Für weitere Details zu spezifischen Funktionen:

• Hinweise zu Änderungen der Versionsnummer - Detaillierte Kanalversionierungsstrategie
• Kanalverwaltung - Vollständige Kanalkonfigurationsreferenz
• Updateverhalten - Natürliche Versionenverzögerungen und -bedingungen

Fortsetzung von Zielversionen

Wenn Sie "Version Zielversionen" verwenden Zielversionen um Kanalrouten und die schrittweise Einführung zu planen, verbinden Sie es mit Kanälen um die Implementierungsdetails in Kanälen zu erhalten Kanäle für die Implementierungsdetails in Kanäle, Kanäle für die Implementierungsdetails in Kanäle, Beta-Testlösung für den Produktworkflow in Beta-Testlösung, und Versionsziel-Lösung für den Produktworkflow in Versionsziel-Lösung.