Zielversionen

Dieser Leitfaden erklärt, wie man automatisch den neuesten kompatiblen Bundle an Benutzer liefert, basierend auf ihrer native App-Version, ähnlich wie Ionic AppFlows Ansatz. Dies sichert eine vereinfachte Update-Verwaltung und schnellere Rollouts aus, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Migrieren Sie von Ionic AppFlow?

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

Übersicht

Capgo's Versionsziel-System ermöglicht Ihnen:

• Kompatible Updates automatisch liefern Benutzern auf der Grundlage ihrer native App-Version
• Verhindern Sie, dass unkompatible Änderungen unverändert an inkompatible App-Versionen gelangen
• Mehrere App-Versionen gleichzeitig ohne komplexes Logik Updates problemlos an bestimmte Benutzergruppen verteilen
• Weshalb Versionsziel-System wichtig ist (Besonders für AppFlow-Nutzer) Warum Versionsziel-System wichtig ist (Besonders für AppFlow-Nutzer)

Weshalb Versionsziel-System wichtig ist (Besonders für AppFlow-Nutzer)

Wenn Sie mit Ionic AppFlow, 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.

AppFlow matchte automatisch Live-Update-Pakete mit nativen App-Versionen ab, um inkompatible JavaScript von älteren nativen Capgo zu verhindern.__CAPGO_KEEP_0__ bietet die gleichen Sicherheitsgarantien

• , mit zusätzlichen Funktionen:
• Mehr granulare Kontrolle über die Versionsabgleich
• Mehrere Strategien (Kanäle, semver, native Einschränkungen)
• API and CLI control alongside dashboard management

__CAPGO_KEEP_0__ und __CAPGO_KEEP_1__ werden gemeinsam mit der Dashboard-Verwaltung gesteuert

• Diese Vorgehensweise ist insbesondere dann nützlich, wenn Sie Benutzer auf verschiedenen Hauptversionen Ihrer App haben (z.B. v1.x, v2.x, v3.x)
• Sie müssen die Rückwärtskompatibilität aufrechterhalten, während Sie die Ausrollung von Bruchänderungen durchführen
• Sie möchten verhindern, dass neue Bundles ältere native code beschädigen
• Sie migrieren die Benutzer allmählich von einer Version zur anderen
• Sie migrieren von AppFlow und möchten die gleiche Sicherheit bei der Aktualisierung aufrechterhalten

Wie es funktioniert

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

1. Native Version Constraints: Verhindern Sie, dass Bundles an inkompatible native Versionen geliefert werden
2. Channel-Based Routing: Routen Sie verschiedene App-Versionen zu verschiedenen Update-Kanälen
3. Semantic Versioning Kontrolle: Aktuell blockieren Sie Updates über Major/Minor/Patch-Grenzen
4. Geräte-Ebene Überschreibungen: Ziehen Sie sich auf bestimmte Geräte oder Benutzergruppen

Versionen-Abgleich-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: Kanalbasierte Versionen-Route

Dies ist die empfohlene Vorgehensweise für die Verwaltung von Bruchänderungen und großen Versionen-Updates. Es ähnelt dem Liefermodell von AppFlow.

Beispiel Szenario

• App v1.x (100.000 Benutzer) → production Kanal
• App v2.x (50.000 Benutzer mit Bruchstellenä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 Sie Versionsspezifische Pakete

# 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 basierend auf dem defaultChannel in ihrem installierten App-Bundle. Keine JavaScript code-Änderungen erforderlich!

Vorteile

• Keine code-Änderungen - Die Kanalrouting erfolgt automatisch
• Klare Trennung - Jede Version hat ihren eigenen Update-Pipeline
• Flexible Zielgruppenzugehörigkeit - Push-Updates für bestimmte Versionsgruppen
• Sichere Rollouts - Bruchstellen werden niemals in inkompatiblen Versionen erreicht

Strategie 2: Kontrolle über semantische Versionsnummern

Nutzen Sie Capgo’s integrierte semantische Versionskontrolle um Updates über Versionsgrenzen hinweg zu verhindern.

Deaktivieren Sie die automatische Aktualisierung über Hauptversionen

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

Diese Konfiguration bedeutet:

• Benutzer auf der Anwendungsversion 1.2.3 werden Updates bis zu 1.9.9
• Benutzer werden NICHT Version 2.0.0 automatisch
• Verhindert, dass sich verändernde Änderungen an älteren nativen code
• Die Vergleichsoperation verwendet die native Basislinie, die als version_build

Feinabstimmungsoptionen

# 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 Semantic Versioning (semver) für Ihre App-Versionen einhalten. Stellen Sie sicher, dass Ihre Versionsnummern dem Format entsprechen. MAJOR.MINOR.PATCH Strategie 3: Native Version Constraints

Abschnitt mit dem Titel „Strategie 3: Native Version Constraints“

Verzögerte Bedingung für native Version

Verwendung der nativeVersion Delay Condition

Wenn Sie ein Bundle hochladen, können Sie eine Mindestversion der 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 native Version 1.x erhalten DIESES BUNDLE NICHT. Nur Geräte auf 2.0.0+ erhalten es. Dies ist perfekt für Updates, die neue native APIs oder Plugins erfordern.

Verwendungsfälle

1. Neuer Plugin für native Version erforderlich

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

2. Native API Änderungen durchbrechen

   # 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

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

Im Kanal-Einstellungen aktivieren

In der Capgo-Oberfläche:

1. Gehe zu Kanäle → Wähle deinen Kanal
2. Aktivieren “Automatische Downgrade unter Native deaktivieren”
3. Änderungen speichern

Oder über CLI:

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

Beispiel

• Gerät des Benutzers: Native-Version 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 Sie die Kanalzuweisung für bestimmte Geräte oder Benutzergruppen.

Zwingen Sie eine spezifische 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' })
  }
}

Zentraleinstellungen Geräteumgehung

In der Capgo Zentraleinstellung:

1. Zu Geräte → Gerät finden
2. Klicken Kanal setzen oder Version setzen
3. Mit spezifischem Kanal oder Bundle-Version überschreiben
4. Gerät erhält Updates von übergeordneter 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. Initialisierung (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-Änderung (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 auf beide 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 Versionsverteilung

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

• Wie viele Benutzer sind auf v1 gegenüber v2
• Verbreitung 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)

Kanal-Vorrang

Wenn mehrere Kanal-Konfigurationen existieren, verwendet Capgo diese Vorrangfolge:

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

Wenn eine App eines Benutzers

hat defaultChannel: 'v2' aber Sie überschreiben ihren Gerät zu 'beta' in der Konsole erhalten sie Updates von dem 'beta' Kanal.

Die Geräte-Überschreibungs-Oberfläche listet nur Überschreibungen auf, die aus der Konsole oder dem öffentlichen API. Aufruf setChannel() aus der App validiert den Kanal mit dem Backend, dann speichert es lokal auf dem Gerät.

Best Practices

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 Zweige

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

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

• Benutzer aktualisieren sie sich auf neueren nativen Versionen?
• 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 Zielgruppenvergleich funktioniert:

Funktion	Ionic AppFlow	Capgo
Version-basierte Routensteuerung	Automatisch basierend auf der nativen Version	Automatisch über defaultChannel + mehrere Strategien
Semantische Versionsnummerierung	Grundlegende Unterstützung	Erweitert mit --disable-auto-update (Major/Minor/Patch)
Nativversionseinschränkungen	Manuelle Konfiguration in AppFlow-Dashboard	Eingebauter --native-version Flagge in CLI
Kanalverwaltung	Web-UI + CLI	Web-UI + CLI + API
Geräteüberschreibungen	Eingeschränkte Geräteeinfluss	Vollständige Kontrolle über Dashboard/API
Verhinderung von Downgrades	Ja	Ja über --disable-downgrade
Wartung mehrerer Versionen	Manuelle Verwaltung von Branchen/Kanälen	Automatisiert mit Kanalvorrang
Selbsthosting	Nein	Ja (vollständige Kontrolle)
Version-Analytik	Grundlegend	Detaillierte pro-Version-Metriken

AppFlow-Gleichheit und darüber hinaus

Capgo bietet alle Versionen-Zielfähigkeiten die AppFlow bot, plus zusätzliche Kontrollmechanismen. Wenn Sie sich auf AppFlows automatische Versionszuordnung 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 Kanaleinstellungen disable-auto-update Einstellungen

   npx @capgo/cli channel list

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

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

Falsche Version des Bundles erhalten

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. Native Version überprüfen: Bestätigen --native-version Die Flagge wurde korrekt verwendet

Änderungen, die alte Versionen betreffen

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

Migration von Ionic AppFlow

Wenn Sie von Ionic AppFlow migrieren Ionic AppFlowVersion-Zielarbeiten funktionieren sehr ähnlich in Capgo, mit verbesserten Flexibilität:

Konzeptkarte

AppFlow-Konzept	Capgo-Äquivalent	Hinweise
Deploy-Kanal	Capgo-Kanal	Das gleiche Konzept, aber mächtiger
Native Version Lock	--native-version flagge	Mehr granulare Kontrolle
Kanalpriorität	Kanalvorrang (Überprüfung → Cloud → Standard)	Mehr transparenter Vorrang
Zielsystem	Kanal + semver-Kontrollen	Mehrere Strategien verfügbar
Produktionskanal	production Kanal (oder beliebiger Name)	Flexible Namensgebung
Git-basierte Bereitstellung	CLI-Paket hochladen von 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 die Kompatibilitätsprobleme an
3. API Zugriff: Vollständige programmatische Kontrolle über die Versionsziele
4. Selbst-Hosting: Option, um Ihre eigene Update-Server mit gleicher Versionslogik zu betreiben

Migrationsschritte

1. Ihre AppFlow-Kanäle zu Capgo Kanälen (üblicherweise 1:1)
2. Setzen defaultChannel im capacitor.config.ts für jede Hauptversion
3. Configure semver Regeln wenn Sie eine automatische Blockierung an Versionsgrenzen wünschen
4. Upload versionsspezifische Bundles mit --native-version Flagge
5. Überwachen Sie die Versionenverteilung in Capgo Dashboard

Vollständiger Migration Guide

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

Erweiterte Muster

Schrittweise Veröffentlichung 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

// 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 Versions-spezifische Lieferung von Updates:

1. Kanalbasierte Routing: Automatische Versions-Trennung via defaultChannel
2. Semantische Versionsnummer: Verhindere Updates über Haupt-/Minor-/Patch-Grenzen
3. Nativ-versionsbeschränkungen: Erforderliche Mindestnativversion für Bundles
4. Auto-Downgrade-Verhinderung: Liefern Sie niemals ältere Bundles an neueren nativen Versionen
5. Geräte-Überschreibungen: 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 Ansätze, die am besten zu Ihrer App-Versionierung und -Veröffentlichungsworkflow passen.

Für weitere Details zu bestimmten Funktionen:

• Leitfaden für Änderungen - Detaillierte Strategie für die Versionsnummerierung von Kanälen
• Kanalverwaltung - Vollständige Referenz für die Kanalkonfiguration
• Aktualisierungsverhalten - Native Version verzögern und Bedingungen

Weitermachen von Zielversionen

Wenn Sie "Version Targeting" verwenden, um Kanalroutings und Rollouts in Phasen zu planen, verbinden Sie es mit Version Targeting um Kanalroutings und Rollouts in Phasen zu planen Kanäle für die Implementierungsdetails in Kanäle, 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 Version-Zielsystem für den Produktworkflow in Version-Zielsystem.