Zum Inhalt springen

Versionierung zielgerichtet

Diese Anleitung erklärt, wie man den neuesten kompatiblen Bundle automatisch an Benutzer ausliefern kann, basierend auf ihrer native App-Version. ähnlich der Ansätze von Ionic AppFlowDadurch wird die Update-Verwaltung vereinfacht und die Rollouts beschleunigt, während gleichzeitig Kompatibilitätsprobleme vermieden werden.

Capgo's Versionsziel-System ermöglicht Ihnen:

  • Kompatible Updates automatisch bereitstellen automatisch an Benutzer basierend auf ihrer native App-Version
  • Verhindere Änderungen mit Auswirkungen auf die Funktionalität von inkompatiblen App-Versionen aus
  • von inkompatiblen App-Versionen Verwalten Sie mehrere App-Versionen
  • Updates ohne Hürden bereitstellen spezifischen Benutzergruppen

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

Sektion mit dem Titel “Weshalb Version-Zielgruppierung wichtig ist (Besonders für AppFlow-Nutzer)”

If you’re familiar with Ionic AppFlowvertraut sind, wissen Sie, wie wichtig es ist, sicherzustellen, dass Benutzer nur kompatible Updates erhalten. AppFlow matchte automatisch live update-Pakete mit nativen App-Versionen, um inkompatible JavaScript von älteren nativen code-Versionen fernzuhalten.

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

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

Dieser Ansatz 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 Weiterentwicklung aufrechterhalten, während Sie wichtige Änderungen durchführen
  • Sie möchten verhindern, dass neue Pakete ä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 Update-Sicherheit aufrechterhalten

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

  1. Nativversionenbeschränkungen: Verhindere, dass Pakete inkompatiblen native Versionen zugewiesen werden
  2. Kanalbasierte Routing: Routiere verschiedene App-Versionen zu verschiedenen Update-Kanälen
  3. Semantische Versionskontrolle: Blockiere automatisch Updates über Major/Minor/Patch-Grenzen
  4. Geräteebene-Überschreibungen: Ziele spezifische Geräte oder Benutzergruppen
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]

Dies ist die empfohlene Vorgehensweise für die Verwaltung von Bruchänderungen und großen Versionsupdates. Sie ähnelt dem Liefermodell von AppFlow.

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

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

Schritt 1: Konfigurieren Sie für jede Hauptversion Kanäle
// 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
}
}
};

Zwischenablage kopieren

Schritt 2: Erstellen Sie Kanäle
Terminalfenster
# 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: Upload von Versionsspezifischen Paketen

Schritt 3: Upload von Versionsspezifischen Paketen
Terminalfenster
# 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
  • Keine code-Änderungen - Kanalrouting erfolgt automatisch
  • Scharfe Trennung - Jede Version hat ihren eigenen Update-Pipeline
  • Flexible Zielgruppen - Push-Updates an bestimmte Versionen senden
  • Sichere Rollouts - Bruchstellen werden niemals an inkompatible Versionen weitergeleitet

Verwenden Sie Capgo’s eingebauten semantischen Versionskontrollen um Updates über Versionsgrenzen zu verhindern.

Automatische Updates über große Versionen deaktivieren

Abschnitt: "Automatische Updates über große Versionen deaktivieren"
Terminalfenster
# 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:

  • Benutzer mit der App-Version 1.2.3 werden Updates bis zu 1.9.9
  • Benutzer werden NICHT Updates für die Version 2.0.0 automatisch
  • Verhindert, dass wichtige Änderungen älteren nativen code erreichen.
  • Die Vergleichung verwendet die native Basislinie, die als version_build
Terminal-Fenster
# 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

Legen Sie eine Mindestversion des native Apps (min_update_version) auf jedem Bundle fest, so dass Capgo nur auf Geräten mit einer neuen genügenden native Binärdatei geliefert wird.

Dies verwendet die Kanal Metadaten Strategie (--disable-auto-update metadata) plus --min-update-version oder --auto-min-update-version auf Upload. Es gibt keinen --native-version CLI Flag.

Abschnitt mit dem Titel ‘Kanal Metadaten aktivieren’

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

Setzen Sie eine Mindestversion für native Code auf Upload

Abschnitt mit Titel “Setzen Sie eine Mindestversion für native Code auf Upload”

Wenn Sie ein Bundle hochladen, geben Sie die niedrigste native Version an, die es empfangen kann:

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

Lassen Sie Capgo die untere Grenze von der nativen Paketkompatibilität bestimmen:

Terminalfenster
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version
  1. Neue native Plugin-Anforderung

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

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

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

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

Im Capgo-Dashboard:

  1. Zu Kanäle → Deinen Kanal auswählen
  2. Aktivieren “Unter Native deaktivieren“
  3. Änderungen speichern

Oder via CLI:

Terminal-Fenster
npx @capgo/cli@latest channel set production --no-downgrade
  • Gerät des Benutzers: Native-Version 1.2.5
  • Kanal-Paket: Version 1.2.3
  • Erfolg: Aktualisierung wird blockiert (würde eine Downgrade bedeuten)

Das ist nützlich, wenn:

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

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

Zwingen Sie eine spezifische Version für Tests

Section titled “Force Specific Version for Testing”
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' })
}
}

Zentraleinstellung Gerät überschreiben

Überschrift: "Geräteüberschreibung im Dashboard"

In der Capgo Zentraleinstellung:

  1. Gehe zu Geräte → Gerät finden
  2. Klicken Kanal setzen oder Version setzen
  3. Übernehmen Sie eine bestimmte Kanal- oder Paketversion
  4. Das Gerät erhält Updates von der überschriebenen Quelle

Ein vollständiges Beispiel, das alle Strategien kombiniert:

Terminal-Fenster
# 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.Konfigurationsdatei.ts
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production',
}
}
};
Terminalfenster
# 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
}
}
};
Terminalfenster
# 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"

Use the Capgo dashboard to track:

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

Sobald die v1-Nutzung unter der Schwellenwert liegt:

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

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. lokale Plugin-Kanal durch setChannel() - Auf dem Gerät gespeichert und nicht in der Geräte-Überschreibungs-UI angezeigt
  3. standardChannel in capacitor.config.ts
  4. Standardkanal (Cloud-Einstellung) - Niedrigste Priorität
// ✅ 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

Section titled “2. Use Semantic Versioning”
Terminalfenster
# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
# ❌ Bad
1.0 → 1.1 → 2 → 2.5
Terminal-Fenster
# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions
Terminal-Fenster
# 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

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

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

Für Teams, die von Ionic AppFlowHier ist eine Übersicht, wie Capgos Versionszielverfolgung funktioniert.

FunktionIonic AppFlowCapgo
Versionsbasierte RoutenführungAutomatisch basierend auf der native VersionAutomatisch über defaultChannel + mehrere Strategien
Semantische VersionsnummerGrundlegende UnterstützungErweitert mit --disable-auto-update (Major/Minor/Patch)
Native VersionsbeschränkungenManuelle Konfiguration in AppFlow-DashboardEingebettet --min-update-version / --auto-min-update-version mit Metadatenkanälen
KanalverwaltungWeb UI + CLIWeb UI + CLI + API
Geräte-ÜberschreibungenLimitierte Geräte-EinstellungenVollständige Kontrolle über API
Verhinderung von DowngradesJaJa über --no-downgrade
Multi-Versionen-VerwaltungManuelle Branchen- und KanalverwaltungAutomatisiert mit Kanal-Vorrang
Selbst-HostingNoJa (vollständige Kontrolle)
Version-AnalytikGrundlegendDetaillierte pro-Version-Metriken

Überprüfen Sie Folgendes:

  1. Kanalzuweisung: Verify device is on correct channel

    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 disable-auto-update Einstellung

    Terminalfenster
    npx @capgo/cli channel list
  4. GeräteumstellungÜberprüfe, ob das Gerät eine manuelle Übernahme hat.

    • Zurück zur Oberfläche → Geräte → Gerät suchen → Kanal/Version überprüfen
  1. Standardkanal überprüfen: Stellen Sie sicher, dass der richtige Kanal in capacitor.config.ts
  2. Bundle hochladen überprüfen: Überprüfe, ob das Bundle an die beabsichtigte Kanal hochgeladen wurde
  3. Mindestupdateversion überprüfen: Bestätigen --min-update-version (oder --auto-min-update-versionwar gesetzt und das Kanal verwendet --disable-auto-update metadata
  1. Unmittelbare Korrektur: Betroffene Geräte auf sicheren Bundle umstellen
    • Dashboard → Geräte → Masseauswahl → Version setzen
  2. Langfristige Korrektur: Versionierte Kanäle erstellen und separate Zweige pflegen
  3. Vorbeugung: Alle Updates auf repräsentativen Geräten vor der Rollout testen

Wenn Sie von Ionic AppFlow migrieren Ionic AppFlowVersionzielung funktioniert bei der Migration von Capgo ähnlich, mit verbesserter Flexibilität:

AppFlow-KonzeptCapgo-ÄquivalentHinweise
Veröffentlichungs-KanalCapgo-KanalGleiche Konzeption, mehr Leistung
Native Versionsfreigabe--min-update-version / --auto-min-update-versionMehr präzise Kontrolle
KanalprioritätKanalvorrang (Überschreiben → Cloud → Standard)Mehr transparenter Vorrang
Deployment TargetKanal + semver-KontrollenMehrere Strategien verfügbar
Produktionskanalproduction Kanal (oder beliebiger Name)Flexible Namensgebung
Git-basierte BereitstellungCLI Paket-Upload aus der BranchSelbe Workflow
Automatische VersionszuordnungdefaultChannel + VersionsbeschränkungenVerbessert mit mehreren Strategien
  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
  1. Deine AppFlow-Kanäle zu Capgo Kanälen (üblicherweise 1:1) abbilden
  2. Setze defaultChannel context capacitor.config.ts für jede Hauptversion
  3. Konfigurieren Sie semver-Regeln Wenn Sie eine automatische Blockierung an Versionsgrenzen wünschen
  4. Versionsspezifische Pakete hochladen mit --min-update-version (channel muss die Metadaten-Strategie verwenden)
  5. (Kanal muss die Metadatenstrategie verwenden) im Capgo Dashboard

AppFlow zu __CAPGO_KEEP_0__-Migration-Leitfaden

Section titled “Advanced Patterns”

Schrittweise Bereitstellung nach Version

Schrittweise Einführung durch Versionsziele
// 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' })
}
}
// 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()
}
}
// 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 })
}
}

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

  1. Kanalbasierte Routing: Automatische Versionszuteilung über defaultChannel
  2. Semantic Versioning: Verhindere Updates über Haupt-/Mittel-/Patchgrenzen
  3. Native Version Einschränkungen: Erforderliche Mindestversion für native Versionen
  4. Automatische Downgrade-Vermeidung: Liefer nie ältere Pakete an neueren native Versionen
  5. Geräte-Überschreibungen: Manuelle Kontrolle für Tests und Zielgruppen

Indem Sie diese Strategien kombinieren, können Sie AppFlow-ähnliche automatische Update-Lieferungen mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die geeignete Methode, die Ihren Anwendungs-versions- und -veröffentlichungsworkflow am besten entspricht.

: Weitere Details zu spezifischen Funktionen:

Wenn Sie Live Updates verwenden Versionierung Ziele to plan channel routing and staged rollout, connect it with Kanäle für die Implementierungsdetails in Kanälen Kanäle für die Implementierungsdetails in Kanälen Kanäle für die Implementierungsdetails in Kanälen Beta-Testlösung für das Produktworkflow in der Beta-Testlösung, und Version Targeting Solution für das Produktworkflow in der Versionziel-Lösung.