Versionziel

Diese Anleitung erklärt, wie man automatisch dem neuesten kompatiblen Bundle an Benutzer liefert, basierend auf ihrer native App-Version, ähnlich wie bei Ionic AppFlows AnsatzDies stellt eine vereinfachte Update-Verwaltung und schnellere Rollouts sicher, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Von Ionic AppFlow migrieren?

Wenn Sie von Ionic AppFlow kommen, ist diese Anleitung 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 die AppFlow-Migration-Leitfaden für Schritt-für-Schritt-Anweisungen zur Migration.

Übersicht

Capgo’s Versionsziel-System ermöglicht Ihnen:

• Kompatible Updates automatisch liefern an Benutzer basierend auf ihrer native App-Version
• Verhindern von Änderungen, die die App-Version inkompatibel machen Mehrfach-App-Versionen gleichzeitig ohne komplexes Logik verwalten
• Updates ohne Hürden bereitstellen. Automatisch kompatible Updates liefern
• an Benutzer basierend auf ihrer native App-Version für bestimmte Benutzersegmente

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

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

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

• Feinere Kontrolle über die Versionsabgleich
• 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 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 Wartung aufrechterhalten, während Sie wichtige Änderungen umsetzen
• Sie möchten verhindern, dass neue Bundles ä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 der Aktualisierung aufrechterhalten Wie es funktioniert

Abschnitt mit dem Titel „Wie es funktioniert“

Capgo uses a multi-layered approach to match users with compatible updates:

1. : Verhindern Sie, dass Bundles an inkompatiblen native Versionen geliefert werdenSie haben Benutzer auf verschiedenen Hauptversionen Ihrer App (z.B. v1.x, v2.x, v3.x)
2. Kanalbasierte Routensteuerung: Routen unterschiedliche App-Versionen zu unterschiedlichen Update-Kanälen
3. Semantische Versionskontrolle: Automatisch Updates über Major/Major/Minor-Grenzen blockieren
4. Geräteebene-Überlagerungen: Ziele 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 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 Versionsrouting

Dies ist der empfohlener Ansatz für die Verwaltung von Änderungen, die das Produkt brechen, und wichtige Versionsupdates. Es ähnelt dem Liefermodell von AppFlow.

Beispielszenario

• App v1.x (100.000 Benutzer) → production Kanal
• App v2.x (50.000 Benutzer mit Änderungen, die das Produkt brechen) → 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 zugewiesenen Kanal basierend auf dem defaultChannel in ihrem installierten App-Paket. Keine JavaScript code-Änderungen erforderlich!

Vorteile

• Null code-Änderungen - Das Routing über Kanäle erfolgt automatisch
• Klare Trennung - Jede Version hat ihren eigenen Update-Pfad
• Flexible Zielgruppen - Push-Updates für bestimmte Versionsgruppen
• Sichere Rollouts - Bruchstellen ändern nie inkompatible Versionen

Strategie 2: Kontrolle über semantische Versionierung

Verwenden Sie Capgo’s integrierte semantische Versionierungskontrollen um Updates über Versionsgrenzen zu verhindern.

Deaktivieren Sie die Auto-Update-Funktion über Hauptversionen

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

Diese Konfiguration bedeutet:

• Benutzer mit der Anwendungsversion 1.2.3 werden Aktualisierungen bis zu 1.9.9
• Benutzer werden NICHT Aktualisierungen der Version 2.0.0 automatisch
• Verhindert, dass sich verändernde Änderungen an älteren nativen code verbreiten

Granulares 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 semantic versioning (semver) für Ihre App-Versionen einhalten. Stellen Sie sicher, dass Ihre Versionsnummern dem 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 inkompatiblen Geräten zu verhindern.

Mit nativeVersion Delay Bedingung

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

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. Zum Kanäle → Wählen Sie Ihren Kanal
2. Aktivieren “Deaktivieren Sie die automatische Downgrade unter native”
3. Speichern Sie die Ä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
• Ergebnis: Aktualisierung blockiert (würde eine Downgrade darstellen)

Dies ist nützlich, wenn:

• Benutzer haben eine neuere Version manuell aus dem App-Store installiert
• Sie benötigen sicherzustellen, dass Benutzer immer die neuesten Sicherheitspatches erhalten
• Sie möchten Regression-Bugs 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' })
  }
}

Dashboard Geräteumgehung

Gehen Sie in der Capgo-Oberfläche:

1. Zu Geräte → Gerät finden
2. Klicken Sie Kanal festlegen oder Version festlegen
3. Mit spezifischem Kanal oder Bundle-Version überschreiben
4. Das Gerät erhält Updates aus 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)

Terminal-Fenster

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

capacitor.Konfiguration.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. Versionen verteilen überwachen

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

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

5. Veraltete Version deaktivieren

Wenn 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-Überschreibung (Dashboard oder API) - Höchste Priorität und sichtbar in der Geräte-Überschreibungs-Oberfläche
2. Lokaler Plugin-Kanal via setChannel() - Auf dem Gerät nur gespeichert und nicht in der Geräte-Überschreibungs-Oberfläche angezeigt
3. defaultChannel in capacitor.config.ts
4. Standardkanal (Cloud-Einstellung) - Niedrigste Priorität

Beispiel für die Vorrangfolge

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

Die Geräte-Überschreibungs-UI listet nur Überschreibungen auf, die aus dem Dashboard oder Public API gesetzt wurden. Aufrufen 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 Major Versions

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

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

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

• Stellen Benutzer auf neueren nativen Versionen um?
• 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 Versionenziel vergleicht:

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)
Nativversionenbeschränkungen	Manuelle Konfiguration in AppFlow-Dashboard	Inbegriffen --native-version Flag in CLI
Kanalverwaltung	Web-UI + CLI	Web-UI + CLI + API
Geräteüberschreibungen	Eingeschränkte Geräteeinflussnahme	Vollständige Kontrolle über die Dashboard/API
Verhinderung von automatischen Downgrades	Ja	Ja über --disable-downgrade
Multi-Version-Wartung	Manuelle Branchen-/Kanalverwaltung	Automatisch mit Kanalvorzug
Selbstbetrieb	Nein	Ja (vollständige Kontrolle)
Versionen-Analyse	Grundlegend	Detaillierte pro-Version-Metriken

AppFlow-Parität 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 → Pakete → Überprüfen Sie die Spalte “Native Version”

3. Semver-Einstellungen: Überprüfen Sie den Kanal des Geräts disable-auto-update Einstellung

   npx @capgo/cli channel list

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

   • Zurück zum Dashboard → Geräte → Gerät suchen → Kanal/Versionsnummer überprüfen

Falsche Version des Bundles geliefert

1. Überprüfen Sie die Standardkanal-Einstellung: Stellen Sie sicher, dass der richtige Kanal im capacitor.config.ts
2. Überprüfen Sie den Bundle-Upload: Prüfe, ob das Bundle an der vorgesehenen Kanal hochgeladen wurde
3. Inspektion der Native Version: Bestätigen --native-version Die Flag-Option wurde korrekt verwendet

Änderungen, die alte Versionen betreffen

1. Eilmaßnahme: Übernehmen Sie auf betroffenen Geräten die sichere Bundle
   • Dashboard → Geräte → Masseauswahl → Version setzen
2. Langfristige Maßnahme: Erstellen Sie kanalverteilte Versionen und halten Sie separate Branches
3. Prävention: Immer Updates auf repräsentativen Geräten vor der Rollout testen

Migration von Ionic AppFlow

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

Konzeptkarte

AppFlow-Konzept	Capgo Äquivalent	Hinweise
Deploy-Kanal	Capgo Kanal	Selben Konzept, mehr Macht
Native Version Lock	--native-version Flagge	Mehr detaillierte Kontrolle
Kanal Priorität	Kanal Vorrang (Übergeordnet → Cloud → Standard)	Mehr transparenter Vorrang
Ziel für die Bereitstellung	Kanal + semver Kontrolle	Mehrere Strategien verfügbar
Produktionskanal	production Kanal (oder beliebiger Name)	Flexible Namensgebung
Git-basierte Bereitstellung	CLI-Paket-Upload aus der Branch	Ebenso 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: Die Dashboard zeigt die Versionenverteilung und Kompatibilitätsprobleme
3. API Zugriff: Vollständige programmatische Kontrolle über die Versionenziel
4. Selbst-Hosting: Option, um Ihre eigene Update-Server mit gleicher Version-Logik zu betreiben

Migrationsschritte

1. Karten Ihre AppFlow-Kanäle zu Capgo Kanälen (üblicherweise 1:1)
2. Einstellungen 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 Bundeln mit --native-version Flagge
5. Überwachen Sie die Versionenverteilung in Capgo-Dashboard

Vollständiger Migration-Leitfaden

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

Erweiterte Muster

Versionenbezogener Schrittweiser Rollout

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

// 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-Testen ü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 über defaultChannel
2. Semantische Versionsnummer: Verhindern Sie Updates über Haupt-/Mittel-/Patch-Grenzen
3. Nativversionenbeschränkungen: Erfordern Sie den Mindestnativversion für Bundles
4. Verhindern von Downgrades: Liefern Sie niemals ältere Bundles an neue native Versionen
5. Geräteüberschreibungen: Manuelle Kontrolle für Testen und Zielsetzen

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 Ansatz, der am besten zu Ihrem Apps Versions- und Bereitstellungsworkflow passt.

Für weitere Details zu bestimmten Funktionen:

• Änderungen im Hinblick auf die Kompatibilität - Detaillierte Strategie zur Versionsverwaltung des Kanals
• Kanalverwaltung - Vollständige Referenz zur Kanalkonfiguration
• Updateverhalten - Native Versionen verzögern und Bedingungen

Fortsetzen Sie mit der Versionszielverfolgung

Wenn Sie " Versionszielverfolgung um Kanalrouting und rollierende Veröffentlichung zu planen und zu verbinden mit 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 Versionziel-Lösung für den Produktworkflow in Versionziel-Lösung.