Zielversion

Diese Anleitung erklärt, wie man automatisch den neuesten kompatiblen Bundle an Benutzer liefert, basierend auf ihrer native App-Version, ähnlich wie Ionic AppFlow’s Ansatz. Dies stellt eine vereinfachte Update-Verwaltung und schnellere Bereitstellungen sicher, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Migrieren Sie von Ionic AppFlow?

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

Übersicht

Capgo's Versionsziel-System ermöglicht Ihnen:

• Automatisches Liefern von kompatiblen Updates an Benutzer auf der Grundlage ihrer native App-Version
• Verhindern von Bruchänderungen von inkompatiblen App-Versionen
• Mehrere App-Versionen verwalten gleichzeitig ohne komplexes Logik
• Aktualisierungen ohne Komplikationen bereitstellen spezifischen Benutzergruppen

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

Wenn Sie mit Ionic AppFlowbekannt sind, wissen Sie, wie wichtig es ist, sicherzustellen, dass Benutzer nur kompatible Updates erhalten. AppFlow matchte automatisch Live-Update-Bundles mit nativen App-Versionen, um inkompatibles JavaScript von älteren nativen code zu verhindern.

Capgo bietet die gleichen Sicherheitsgarantienmit zusätzlichen Funktionen:

• Mehr granulare Kontrolle über Versionsabgleich
• Mehrere Strategien (Kanäle, semver, native Einschränkungen)
• Bessere Sichtbarkeit in die Versionsverteilung
• API und CLI Kontrolle neben 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ärtskompatible Weiterentwicklung aufrechterhalten, während Sie wichtige Änderungen durchführen
• Sie möchten verhindern, dass neuerere Pakete ältere native code beschädigen
• Sie migrieren Benutzer allmählich von einer Version zur anderen
• Sie migrieren von AppFlow und möchten die gleiche Sicherheit bei Updates aufrechterhalten 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 Einschränkungen: Verhindern Sie, dass Bundles an inkompatiblen native Versionen geliefert werden
2. Kanalbasierte Routing: Leiten Sie verschiedene App-Versionen an verschiedene Update-Kanäle weiter
3. Semantische Versionskontrolle: Blockieren Sie automatisch Updates über Major/Major/Minor-Grenzen
4. Geräteebene-Überschreibungen: Ziel spezifische Geräte oder Benutzergruppen

Versionsabgleich-Fluss

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

Strategie 1: Kanalbasierte Versionsrouting

Dies ist der __CAPGO_KEEP_0__ empfohlene Ansatz

für die Verwaltung von Änderungen und großen Versionsupdates. Er ähnelt dem Liefermodell von AppFlow.

• Abschnitt mit dem Titel „Beispiel-Szenario” App v1.x production (100.000 Benutzer) →
• Kanal (50.000 Benutzer mit Änderungen, die das Produkt beeinträchtigen) → v2 Kanal
• App v3.x (10.000 Beta-Testern) → v3 Kanal

Implementierung

Kopieren Sie auf die Zwischenablage

// 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: Kanäle erstellen

# 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: Versions-spezifische Pakete hochladen

# 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 zugewiesenen Kanal auf der Grundlage des defaultChannel in ihrem installierten App-Bundle. Keine JavaScript-code-Änderungen erforderlich!

Vorteile

• Null code Änderungen - Der Kanalrouting erfolgt automatisch
• Klare Trennung - Jede Version hat ihren eigenen Update-Pfad
• Flexible Zielgruppen - Push-Updates für bestimmte Versionen
• Sichere Rollouts - Bruchstellen werden nie in inkompatible Versionen geliefert

Strategie 2: Kontrolle über semantische Versionierung

Verwenden Sie Capgo’s integrierte semantische Versionskontrolle, um Updates über Versionsgrenzen hinweg 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 mit der App-Version 1.2.3 werden Updates bis zur 1.9.9
• Benutzer werden NICHT Updates der Version 2.0.0 automatisch erhalten
• Verhindert Änderungen, die ältere native code beschädigen

Granulare Kontrollmöglichkeiten

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (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 für Ihre App-Versionen Semantic Versioning (semver) einhalten. Stellen Sie sicher, dass Ihre Versionsnummern dem Format entsprechen. MAJOR.MINOR.PATCH Strategie 3: Einschränkungen für native Versionen

Abschnitt mit dem Titel “Strategie 3: Einschränkungen für native Versionen”

Copy to clipboard

Mit nativeVersion Delay Bedingung verwenden

Wenn Sie ein Bundle hochladen, können Sie eine Mindestversion für 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 mit native Version 1.x erhalten DIESES BUNDLE NICHT. Nur Geräte mit 2.0.0+ erhalten es. 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. 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: Vermeidung von automatischen Downgrades

Verhindere, 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 → Wähle deinen Kanal
2. Aktivieren „Deaktivieren Sie die automatische Downgrade unter native“
3. Speichern Sie Änderungen

Oder über CLI:

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

Beispiel

• Geräte des Benutzers: Native Version 1.2.5
• Kanalbundle: Version 1.2.3
• Ergbnis: Aktualisierung ist blockiert (würde eine Downgrade bedeuten)

Dies ist nützlich, wenn:

• Benutzer haben manuell eine neuere Version aus dem App-Store installiert
• Sie benötigen sicherzustellen, dass Benutzer immer die neuesten Sicherheitspatches haben
• Sie möchten Regressionsfehler verhindern

Strategie 5: Geräteebene Zielsetzung

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

Zwingen einer bestimmten Version für Testzwecke

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äteumgehung

Gehen Sie in der Capgo-Übersicht:

1. Zu Geräte → Gerät finden
2. Klicken Kanal festlegen oder Version festlegen
3. Mit einer spezifischen Kanal- oder Paketversion überschreiben
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

1. Initialisierung (App v1.0.0)

Terminalfenster

# 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. Updates auf beide Versionen pushen

# 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. Versionsverteilung überwachen

Verwende das Capgo-Dashboard, um zu überwachen:

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

5. Veraltete Version deaktivieren

Sobald die v1-Nutzung unter der Schwellenwert liegt:

# 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 Kanal-Konfigurationen existieren, verwendet Capgo diese Vorrangfolge:

1. Geräte-Übernahme (Dashboard oder API) - Höchste Priorität
2. Cloud-Übernahme über setChannel() Anruf
3. defaultChannel in capacitor.config.ts
4. Standard-Kanal (Cloud-Einstellung) - Niedrigste Priorität

Vorrangbeispiel

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

Gute Praktiken

1. Setzen Sie immer defaultChannel für Hauptversionen

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

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Halten Sie separate Branches

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

Regelmäßig überprüfen Sie Ihren Dashboard:

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

Vergleich mit Ionic AppFlow

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

Funktion	Ionic AppFlow	Capgo
Versionsbasierte Routing	Automatisch basierend auf der native Version	Automatisch über defaultChannel + mehrere Strategien
Semantische Versionsnummer	Grundlegende Unterstützung	Erweitert mit --disable-auto-update (Major/Minor/Patch)
Native Versionenbeschränkungen	Manuelle Konfiguration im AppFlow-Dashboard	Eingebaut --native-version Flag in CLI
Kanalverwaltung	Web UI + CLI	Web UI + CLI + API
Geräteüberschreibungen	Eingeschränkte Geräteeinstellungen	Vollständige Kontrolle über das Dashboard/API
Verhinderung von automatischen Downgrades	Ja	Ja über --disable-downgrade
Wartung mehrerer Versionen	Manuelle Verwaltung von Branchen und Kanälen	Automatisiert mit Vorrang des Kanals
Selbsthosting	Nein	Ja (vollständige Kontrolle)
Version-Analytik	Grundlegend	Detaillierte pro-Version-Metriken

AppFlow-Äquivalenz und mehr

Capgo bietet alle Funktionen zur Versionszielverwaltung die AppFlow bot, plus zusätzliche Kontrollmechanismen. Wenn Sie sich auf AppFlows automatische Versionszuweisung verlassen haben, finden Sie in Capgo eine gleich sichere Lösung 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. Versionseinschränkungen: Überprüfen Sie, ob das Bundle native Versionen anfordert

   • Dashboard → Pakete → Überprüfen Sie die Spalte "Native Version"

3. Semver-Einstellungen: Überprüfen Sie die Einstellung des Kanals disable-auto-update setting

   npx @capgo/cli channel list

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

   • Zentraleinstieg → Geräte → Gerät suchen → Kanal-Version überprüfen

Bundle an falsche Version geliefert

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

Änderungen, die alte Versionen betreffen

1. Eilmaßnahme: Übernehmen Sie auf betroffene Geräte eine sichere Bundle
   • Zentrale Oberfläche → Geräte → Masseauswahl → Version festlegen
2. Langfristige Lösung: Erstellen Sie kanalisierte Versionen und halten Sie separate Branches
3. Vorbeugung: Testen Sie Updates immer auf repräsentativen Geräten vor der Rollout

Migration von Ionic AppFlow

Wenn Sie von Ionic AppFlow, funktioniert die Version-Zielsetzung in Capgo sehr ähnlich, mit verbessertem Flexibilität:

Konzeptkarte

AppFlow-Konzept	Capgo Äquivalent	Hinweise
Veröffentlichungs-Kanal	Capgo Kanal	Das gleiche Konzept, aber mit mehr Macht
Native Version Lock	--native-version Flag	Mehr Kontrolle auf granularer Ebene
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
gitbasierte Bereitstellung	CLI-Paket-Upload aus der Branch	Selbe Workflow
Automatische Versionsübereinstimmung	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 die Versionsziele
4. Selbst-Hosting: Option, eigene Update-Server mit gleicher Versionslogik zu betreiben

Migrationsschritte

1. Mappen Sie Ihre AppFlow-Kanäle zu Capgo Kanälen (üblicherweise 1:1)
2. Setzen Sie defaultChannel in capacitor.config.ts für jede Hauptversion
3. Konfigurieren Sie semver-Regeln Wenn Sie automatische Blockierung an Versionsgrenzen wünschen
4. Versionsspezifische Bundles hochladen mit --native-version Flagge
5. Versionen verteilen in Capgo-Dashboard

Vollständiger Migration-Leitfaden

Für eine vollständige Migrationsanleitung einschließlich SDK-Ersetzung und API-Mapping, siehe den AppFlow zu Capgo-Migration-Leitfaden.

Erweiterte Muster

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

Funktionsschalter nach 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 Routing: Automatische Versionsabtrennung über defaultChannel
2. Semantische Versionsnummer: Verhindere Updates über Haupt-/Mittel-/Patcheschwellen
3. Native Versionsbeschränkungen: Erforderliche Mindestnative Version für Bundles
4. Verhindere automatische Downgrade: Liefern Sie niemals ältere Bundles an neue native Versionen
5. Geräteüberschreibungen: Manuelle Kontrolle für Tests und Zielsetzung

Indem Sie diese Strategien kombinieren, können Sie AppFlow-Style-Updates mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die Ansätze, die am besten zu Ihrer App-Versionierung und -Veröffentlichungsworkflow passen.

Für weitere Details zu spezifischen Funktionen:

• Änderungen im Überblick - Detaillierte Strategie für die Versionsverwaltung von Kanälen
• Kanalverwaltung - Vollständige Referenz für die Kanalkonfiguration
• Aktualisierungsverhalten - Native Versionen verzögern und setzen Bedingungen