Version-Targeting

Dieser Guide erklärt, wie du Nutzern basierend auf ihrer nativen App-Version automatisch das neueste kompatible Bundle auslieferst, ähnlich wie bei Ionic AppFlow. Das vereinfacht das Update-Management, beschleunigt Rollouts und verhindert Kompatibilitätsprobleme.

Von Ionic AppFlow migrieren?

Wenn du von Ionic AppFlow kommst, ist dieser Guide besonders wichtig für dich. AppFlow hat Updates automatisch mit den nativen Versionen abgeglichen, und Capgo bietet dieselbe Funktion mit noch mehr Kontrolle und Flexibilität. Siehe den AppFlow Migrationsleitfaden für eine Schritt-für-Schritt-Anleitung zur Migration.

Übersicht

Das Version-Targeting von Capgo ermöglicht es dir:

• Kompatible Updates automatisch auszuliefern basierend auf der nativen App-Version der Nutzer
• Breaking Changes zu verhindern bei inkompatiblen App-Versionen
• Mehrere App-Versionen zu verwalten gleichzeitig ohne komplexe Logik
• Updates nahtlos ausrollen für spezifische Nutzersegmente

Warum Version Targeting wichtig ist (besonders für AppFlow-Nutzer)

Wenn du bereits mit Ionic AppFlowvertraut bist, weißt du, wie wichtig es ist, dass Nutzer nur kompatible Updates erhalten. AppFlow hat live update Bundles automatisch mit den nativen App-Versionen abgeglichen, um zu verhindern, dass inkompatibles JavaScript an ältere native code ausgeliefert wird.

Capgo bietet dieselben Sicherheitsgarantien, mit zusätzlichen Features:

• Granularere Kontrolle beim Version-Matching
• Mehrere Strategien (Channels, SemVer, native Constraints)
• Bessere Übersicht über die Versionsverteilung
• API und CLI steuern zusammen mit dem Dashboard-Management

Dieser Ansatz ist besonders nützlich, wenn:

• Deine Nutzer verwenden unterschiedliche Hauptversionen deiner App (z. B. v1.x, v2.x, v3.x)
• Du Abwärtskompatibilität wahren musst, während du Breaking Changes ausrollst
• Du verhindern willst, dass neuere Bundles ältere native code zerschießen
• Du Nutzer schrittweise von einer Version auf eine andere migrierst
• Du von AppFlow migrierst und die gleiche Update-Sicherheit beibehalten willst

So funktioniert es

Capgo nutzt einen mehrschichtigen Ansatz, um Nutzer mit kompatiblen Updates zu matchen:

1. Native Versions-Constraints: Verhindert, dass Bundles an inkompatible Native Builds ausgeliefert werden
2. Channel-basiertes Routing: Verschiedene App-Versionen auf unterschiedliche Update-Channels routen
3. Semantic Versioning Steuerung: Updates über Major/Minor/Patch-Grenzen hinweg automatisch blockieren
4. Geräteübergreifende Overrides: Spezifische Geräte oder Nutzergruppen anvisieren

Ablauf der Versionszuordnung

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-basiertes Version-Routing

Dies ist der empfohlene Ansatz für das Management von Breaking Changes und Major-Version-Updates. Er ähnelt dem Delivery-Modell von AppFlow.

Beispielszenario

• App v1.x (100.000 Nutzer) → production Channel
• App v2.x (50.000 Nutzer mit Breaking Changes) → v2 Channel
• App v3.x (10.000 Beta-Nutzer) → v3 Channel

Implementierung

Schritt 1: Channels für jede Major-Version konfigurieren

// 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: Channels erstellen

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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: Versionsspezifische Bundles 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

Automatisches Routing

Wenn Nutzer die App öffnen, verbinden sie sich automatisch mit ihrem zugewiesenen Channel basierend auf der defaultChannel in ihrem installierten App-Bundle. Keine Änderungen an JavaScript-code erforderlich!

Vorteile

• Keine code-Änderungen - Channel-Routing erfolgt automatisch
• Klare Trennung - Jede Version hat eine eigene Update-Pipeline
• Flexibles Targeting - Updates gezielt an Version-Gruppen pushen
• Sichere Rollouts - Breaking Changes erreichen keine inkompatiblen Versionen

Strategie 2: Semantic Versioning Controls

Nutze die integrierten Capgo Semantic Versioning Controls um Updates über Versionsgrenzen hinweg zu verhindern.

Auto-Updates über Major-Versionen hinweg deaktivieren

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

Diese Konfiguration bedeutet:

• Nutzer der App-Version 1.2.3 erhalten Updates bis zu 1.9.9
• Nutzer werden NICHT die Version 2.0.0 automatisch
• Verhindert, dass Breaking Changes ältere native code erreichen
• Der Vergleich nutzt die als Baseline gesendete version_build

Granulare Steuerungsoptionen

# 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 du Semantic Versioning (SemVer) für deine App-Versionen einhältst. Stelle sicher, dass deine Versionsnummern dem MAJOR.MINOR.PATCH format.

Strategie 3: Native-Versionsbeschränkungen

Geben Sie eine minimale native App-Version (min_update_version) pro Bundle an, damit Capgo es nur an Geräte ausliefert, deren native Binary aktuell genug ist.

Dies nutzt die Channel- Metadaten- Strategie (--disable-auto-update metadata) sowie --min-update-version oder --auto-min-update-version beim Upload. Es gibt kein --native-version CLI Flag.

Metadata-Targeting im Channel aktivieren

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Minimale native Version beim Upload festlegen

Geben Sie beim Hochladen eines Bundles die niedrigste native Version an, die dieses erhalten darf:

# 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 Untergrenze für die Native Build-Kompatibilität festlegen:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

So funktioniert es

Mit der Metadata-Strategie überspringen Geräte, deren native Baseline (version_build) unter der Version des Bundles liegt, min_update_version das Update. Nur Geräte auf dieser Version oder höher erhalten es. Siehe Kompatibilität für --auto-min-update-version Details.

Anwendungsfälle

1. Neues natives Plugin erforderlich

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Breaking Changes bei nativen API

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "3.0.0"

3. Schrittweise Migration

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

Strategie 4: Auto-Downgrade-Prävention

Verhindert, dass Nutzer Bundles erhalten, die älter als ihre aktuelle Native Build-Version sind.

In den Channel-Einstellungen aktivieren

Im Capgo Dashboard:

1. Gehe zu Kanäle → Channel auswählen
2. Aktivieren „Disable auto downgrade under native“
3. Änderungen speichern

Oder über CLI:

npx @capgo/cli@latest channel set production --no-downgrade

Beispiel

• Gerät des Nutzers: Native Version 1.2.5
• Channel-Bundle: Version 1.2.3
• Ergebnis: Update wird blockiert (wäre ein Downgrade)

Das ist nützlich, wenn:

• Nutzer haben manuell eine neuere Version aus dem App Store installiert
• Du musst sicherstellen, dass Nutzer immer die neuesten Security-Patches erhalten
• Du möchtest Regression-Bugs verhindern

Strategie 5: Targeting auf Geräteebene

Channel-Zuweisung für bestimmte Geräte oder Nutzergruppen überschreiben.

Spezifische Version für Tests erzwingen

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

Device-Override im Dashboard

Im Capgo Dashboard:

1. Gehe zu Geräte → Gerät suchen
2. Klicken Channel festlegen oder Version festlegen
3. Mit spezifischem Channel oder Bundle-Version überschreiben
4. Das Gerät erhält Updates von der überschriebenen Quelle

Updates testen

Nutze Device Overrides, um Updates auf deinem eigenen Gerät zu testen, bevor du sie für alle Nutzer bereitstellst.

Vollständiger AppFlow-ähnlicher Workflow

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

1. Initiales Setup (App v1.0.0)

# 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',
    }
  }
};

2. Breaking Change veröffentlichen (App v2.0.0)

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

3. Updates für beide Versionen pushen

# 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

Use the Capgo dashboard to track:

• Anzahl der Nutzer auf v1 vs. v2
• Bundle-Adoptionsrate pro Version
• Fehler oder Crashes pro Version

5. Alte Version deprecate

Sobald die v1-Nutzung unter den 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)

Channel-Priorität

Wenn mehrere Channel-Konfigurationen existieren, nutzt Capgo diese Priorisierung:

1. Geräte-Override (Dashboard oder API) – Höchste Priorität, sichtbar im Device Override UI
2. Lokaler Plugin-Channel über setChannel() - Nur auf dem Gerät gespeichert, nicht im Device Override UI sichtbar
3. defaultChannel in capacitor.config.ts
4. Standard-Channel (Cloud-Einstellung) – Niedrigste Priorität

Beispiel der Priorisierung

Wenn die App eines Nutzers hat defaultChannel: 'v2' aber du das Gerät überschreibst auf 'beta' im Dashboard erhalten sie Updates vom 'beta' Channel.

Die Device Override UI listet nur Overrides auf, die über das Dashboard oder Public API gesetzt wurden. Ein Aufruf setChannel() aus der App validiert den Channel mit dem Backend und speichert ihn dann lokal auf dem Gerät.

Best Practices

1. Setze defaultChannel immer 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. Nutze Semantic Versioning

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Separate Branches pflegen

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

# ❌ Bad: Single branch for all versions

4. Vor dem Rollout testen

# 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

Prüfe regelmäßig dein Dashboard:

• Upgraden Nutzer auf neuere Native Builds?
• Haben alte Versionen noch hohen Traffic?
• Should you deprecate old channels?

Vergleich mit Ionic AppFlow

Für Teams, die von Ionic AppFlowmigrieren, zeigt dieser Vergleich das Version Targeting von Capgo:

Funktion	Ionic AppFlow	Capgo
Versionsbasiertes Routing	Automatisch basierend auf der Native Version	Automatisch über defaultChannel + mehrere Strategien
Semantic Versioning	Basis-Support	Erweitert mit --disable-auto-update (major/minor/patch)
Native Version-Constraints	Manuelle Konfiguration im AppFlow Dashboard	Integriert --min-update-version / --auto-min-update-version mit Metadata-Channels
Channel-Management	Web-UI + CLI	Web-UI + CLI + API
Device-Overrides	Begrenzte Kontrolle auf Geräteebene	Volle Kontrolle via Dashboard/API
Schutz vor Auto-Downgrades	Ja	Ja, via --no-downgrade
Wartung mehrerer Versionen	Manuelles Branch-/Channel-Management	Automatisch mit Channel-Priorisierung
Self-Hosting	Nein	Ja (volle Kontrolle)
Versions-Analytics	Basis	Detaillierte Metriken pro Version

AppFlow-Parität und mehr

Capgo bietet alle Version-Targeting-Funktionen, die AppFlow bot, plus zusätzliche Kontrollmechanismen. Wenn du auf das automatische Version-Matching von AppFlow gesetzt hast, ist Capgo genauso sicher, aber flexibler.

Fehlerbehebung

Nutzer erhalten keine Updates

Prüfe Folgendes:

1. Channel-Zuweisung: Überprüfen, ob das Gerät im richtigen Channel ist

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. Versionsbeschränkungen: Prüfe, ob das Bundle native Versionsanforderungen hat

   • Dashboard → Bundles → Spalte „Native Version“ prüfen

3. Semver-Einstellungen: Überprüfe die Channel- disable-auto-update Einstellungen

   npx @capgo/cli channel list

4. Geräte-Override: Prüfen, ob ein manueller Override am Gerät vorliegt

   • Dashboard → Devices → Gerät suchen → Channel/Version prüfen

Bundle an falsche Version geliefert

1. defaultChannel prüfen: Sicherstellen, dass der richtige Channel eingestellt ist capacitor.config.ts
2. Bundle Upload prüfen: Verifizieren, dass das Bundle im richtigen Channel hochgeladen wurde
3. Min. Update-Version prüfen: Bestätigen --min-update-version (oder --auto-min-update-version) wurde gesetzt und der Channel nutzt --disable-auto-update metadata

Breaking Changes, die alte Versionen betreffen

1. Sofortige Lösung: Betroffene Geräte auf ein sicheres Bundle umstellen
   • Dashboard → Devices → Mehrere auswählen → Version festlegen
2. Langfristige Lösung: Versionsspezifische Channels erstellen und separate Branches pflegen
3. Prävention: Updates vor dem Rollout immer auf repräsentativen Geräten testen

Migration von Ionic AppFlow

Wenn Sie migrieren von Ionic AppFlowmigrierst, funktioniert das Version Targeting in Capgo sehr ähnlich, aber mit mehr Flexibilität:

Konzept-Mapping

AppFlow-Konzept	Capgo Äquivalent	Notizen
Deploy-Channel	Capgo Channel	Gleiches Konzept, mehr Power
Native Version-Sperre	--min-update-version / --auto-min-update-version	Granularere Kontrolle
Channel-Priorität	Channel-Reihenfolge (override → cloud → default)	Transparentere Priorisierung
Deployment-Ziel	Channel + SemVer-Steuerung	Mehrere Strategien verfügbar
Production-Channel	production channel (oder ein beliebiger Name)	Flexible Benennung
Git-basiertes Deployment	CLI Bundle-Upload via Branch	Gleicher Workflow
Automatisches Version-Matching	defaultChannel + Versionsbeschränkungen	Erweitert durch mehrere Strategien

Wichtige Unterschiede für AppFlow-Nutzer

1. Mehr KontrolleMit Capgo stehen dir verschiedene Strategien (Channels, SemVer, Native Version) zur Verfügung, die kombiniert werden können
2. Bessere Übersicht: Das Dashboard zeigt die Versionsverteilung und Kompatibilitätsprobleme
3. API Zugriff: Volle programmatische Kontrolle über das Version-Targeting
4. Self-Hosting: Option, einen eigenen Update-Server mit derselben Version-Logik zu betreiben

Migrationsschritte

1. Mappe deine AppFlow-Channels auf Capgo Channels (meist 1:1)
2. Setzen Sie defaultChannel in capacitor.config.ts für jede Major-Version
3. Semver-Regeln konfigurieren wenn Sie automatisches Blockieren an Versionsgrenzen wünschen
4. Versionsspezifische Bundles hochladen mit --min-update-version (Channel muss Metadata-Strategie nutzen)
5. Versionsverteilung überwachen im Capgo Dashboard

Vollständiger Migrationsleitfaden

Für vollständige Migrationsanweisungen, einschließlich des SDK Ersatzes und des API Mappings, siehe den AppFlow zu Capgo Migrationsleitfaden.

Erweiterte Patterns

Schrittweiser Rollout 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 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-Testing ü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 verschiedene Strategien für die versionsspezifische Auslieferung von Updates:

1. Channel-basiertes Routing: Automatische Versionstrennung via defaultChannel
2. Semantische Versionierung: Updates über Major/Minor/Patch-Grenzen verhindern
3. Native Versionsbeschränkungen: Mindestversion der Native Build für Bundles erzwingen
4. Auto-Downgrade-Prävention: Keine älteren Bundles an neuere Native Builds liefern
5. Geräte-Overrides: Manuelle Steuerung für Tests und Targeting

Durch die Kombination dieser Strategien erreichen Sie eine automatische Update-Auslieferung wie bei AppFlow – mit noch mehr Flexibilität und Kontrolle. Wählen Sie den Ansatz, der am besten zu Ihrem Versionierungs- und Deployment-Workflow passt.

Weitere Details zu den einzelnen Features:

• Guide zu Breaking Changes - Detaillierte Strategie zur Channel-Versionierung
• Channel-Management - Vollständige Channel-Konfigurationsreferenz
• Update-Verhalten - Native Version-Verzögerungen und Bedingungen

Weiterlesen zu Version Targeting

Wenn du es nutzt Version-Targeting um Channel-Routing und Staged Rollout zu planen, verbinde es mit Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Beta-Testing-Lösung für den Produkt-Workflow in der Beta-Testing-Lösung, und Version-Targeting-Lösung für den Produkt-Workflow in der Version-Targeting-Lösung.