Zum Inhalt springen

Versionsziel

Diese Anleitung erklärt, wie Sie automatisch dem neuesten kompatiblen Bundle an Benutzer liefern können, basierend auf ihrer native App-Version. Ähnlich wie Ionic AppFlows Ansatz.. Dies stellt eine vereinfachte Update-Verwaltung und schnellere Rollouts sicher, während gleichzeitig Kompatibilitätsprobleme verhindert werden.

Capgo's Versionsziel-System ermöglicht Ihnen:

  • Automatisch kompatible Updates bereitzustellen benötigten Benutzern auf der Grundlage ihrer native App-Version
  • Verhindern Sie Änderungen, die die Anwendung beschädigen von inkompatiblen App-Versionen erreichen
  • Verwalten Sie mehrere App-Versionen gleichzeitig ohne komplexes Logik
  • Aktualisierungen ohne Komplexität bereitstellen benötigten Benutzergruppen

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

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

Wenn Sie mit Ionic AppFlow vertraut sind wissen Sie, wie wichtig es ist, sicherzustellen, dass Benutzer nur kompatible Aktualisierungen erhalten. AppFlow matchte automatisch Live-Update-Bundles mit native App-Versionen, um inkompatibles JavaScript von älteren native __CAPGO_KEEP_0__ zu verhindern., 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.

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

  • Feinere Kontrolle über die Versionsübereinstimmung
  • 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 nützlich, wenn:

  • Sie Benutzer auf verschiedenen Hauptversionen Ihrer App haben (z.B. v1.x, v2.x, v3.x)
  • Sie die rückwärtskompatiblen Änderungen benötigen, während Sie die Unterbrechungen ausrollen
  • Sie verhindern möchten, dass neue Pakete ältere native code beschädigen
  • Sie die Benutzer allmählich von einer Version zur anderen migrieren
  • Sie von AppFlow migrieren und möchte die gleiche Update-Sicherheit aufrechterhalten

Capgo verwendet eine mehrschichtige Ansicht, um Benutzer mit kompatiblen Updates zu verbinden:

  1. Eigenschaften für native Versionen: Verhindert, dass Pakete an inkompatible native Versionen geliefert werden
  2. Kanalbasierte Routing: Routet verschiedene App-Versionen zu verschiedenen Update-Kanälen
  3. Semantische Versionskontrolle: Blockiert automatisch Updates über Haupt-/Mino-/Patch-Grenzen
  4. Geräteebene-Übernahmen: Zieht spezifische Geräte oder Benutzergruppen ins Visier
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 Änderungen, die den Betrieb beeinträchtigen) → v2 Kanal
  • App v3.x (10.000 Beta-Benutzer) → v3 Kanal
// 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 von Kanälen

Abschnitt: "Schritt 2: Erstellen von Kanälen"
Terminalfenster
# 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

Abschnitt: "Schritt 3: Hochladen 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 - Der Kanalrouting erfolgt automatisch
  • - Jede Version hat ihren eigenen Update-Pipeline - Flexible Zielgruppen
  • - Updates werden auf spezifische Versionen gruppiert - Sicherer Rollout
  • - Bruchstellen werden niemals in inkompatible Versionen geliefert - Bruchstellen erreichen niemals inkompatible Versionen

Verwenden Sie Capgos eingebettete semantische Versionskontrollen um Updates über Versionsgrenzen zu verhindern.

Aktualisierungen über Hauptversionen deaktivieren

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

Benutzer mit der App-Version

  • werden Updates bis zu 1.2.3 Version 1.9.9
  • Benutzer erhalten NICHT keine Version 2.0.0 automatisch
  • Verhindert, dass bruchbare Änderungen älteren native code erreichen
  • Die Vergleichung verwendet die native Basislinie, die als version_build
Terminalfenster
# 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, damit Capgo nur an Geräten ausgeliefert wird, deren native Binärdatei neu genug ist.

Dies verwendet die Kanal Metadaten Strategie (--disable-auto-update metadata) plus --min-update-version oder --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Abschnitt: Enable metadata targeting auf dem Kanal

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

Abschnitt: Ermöglichen Sie eine Versionszieleinstellung auf dem Kanal

Setzen Sie eine Mindestversion für native Apps auf Upload

Abschnitt: Setzen Sie eine Mindestversion für native Apps auf Upload

Wenn Sie ein Bundle hochladen, geben Sie die niedrigste native Version an, die es empfangen kann:
# 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 Mindestversion von der Kompatibilität des native Packages bestimmen:

Terminalfenster
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version
  1. Neuer Native-Plugin erforderlich

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

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

    Terminal-Fenster
    # 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. Gehe zu Kanäle Kanal
  2. → Wähle deinen Kanal Enable
  3. “Deaktiviere automatische Downgrade unter native”

Or via CLI:

Oder via __CAPGO_KEEP_0__:
npx @capgo/cli@latest channel set production --no-downgrade
  • Geräte des Benutzers: Native Version 1.2.5
  • Kanal-Paket: Version 1.2.3
  • Ergebnis: Aktualisierung wird blockiert (würde eine Downgrade sein)

Dies 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 erhalten
  • Sie Regression-Bugs verhindern möchten

Strategie 5: Gerätebasierte Zielgruppenabgrenzung

Abschnitt mit dem Titel “Strategie 5: Geräteebene Zielsetzung”

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

Zwingende Spezifische Version für Tests

Zum Clipboard kopieren
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' })
}
}

Abschnitt mit dem Titel “Übersicht Geräteüberschreibung”

In der __CAPGO_KEEP_0__-Übersicht:

In the Capgo dashboard:

  1. Geräte → Gerät finden Klicken
  2. Abschnitt mit dem Titel “Zwingende Spezifische Version für Tests” Kanal festlegen oder Setzen Sie den Kanal oder die Versionsnummer
  3. Überschreiben Sie die Versionsnummer mit einer spezifischen Kanal- oder Bundle-Version
  4. Das Gerät erhält Updates aus der überschriebenen Quelle

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

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

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

  • Wie viele Benutzer sich auf v1 bzw. v2 befinden
  • Zuordnungsrate pro Version
  • Fehler oder Abstürze pro Version

Wenn die Nutzung von v1 unter der Schwellenwert fällt:

Terminalfenster
# 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 Kanalkonfigurationen existieren, verwendet Capgo diese Vorrangreihenfolge:

  1. Geräteüberschreibung (Dashboard oder API) - Höchster Prioritätsstufe und sichtbar in der Geräteüberschreibungs-Oberfläche
  2. Lokaler Pluginkanal 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 (Cloudflare-Einstellung) - Niedrigste Priorität

1. Setzen Sie immer defaultChannel für Hauptversionen

Abschnitt mit dem Titel „1. Setze immer defaultChannel für große Versionen“
// ✅ 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
Terminal-Fenster
# ✅ 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
Terminalfenster
# 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

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

  • Stellen Benutzer eine Upgrade auf neueren native Versionen vor?
  • Bekommen alte Versionen noch viel Traffic?
  • Sollten Sie alte Kanäle deprecieren?

Für Teams, die von Ionic AppFlow migrieren Ionic AppFlow, hier ist ein Vergleich der Capgo-Versionierung:

FeatureIonic AppFlowCapgo
Versionziel__CAPGO_KEEP_0__Version-basierte Routenführung defaultChannel Automatisch auf Basis der nativen Version
Automatisch über+ mehrere StrategienSemantische Versionsnummer --disable-auto-update Grundlegende Unterstützung mit
Native VersionsbeschränkungenManuelle Konfiguration im AppFlow-DashboardEingebaut --min-update-version / --auto-min-update-version mit Metadatenkanälen
KanalverwaltungWeb-UI + CLIWeb-UI + CLI + API
GeräteüberschreibungenEingeschränkte Geräteebene-KontrolleVollständige Kontrolle über Dashboard/API
Verhinderung von DowngradenJaJa über --no-downgrade
Multi-Version-VerwaltungManuelle Verwaltung von Branchen/CanälenAutomatisiert mit Vorrang vor dem Kanal
SelbsthostingNeinJa (vollständige Kontrolle)
Versionen-AnalyseGrundlegendDetaillierte Metriken pro Version

Ü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. Versionsbeschränkungen: Prüfen Sie, ob das Bundle native Versionen erfordert

    • Dashboard → Bundles → Überprüfen Sie die Spalte "Native Version"
  3. Semver-Einstellungen: Überprüfen Sie die des Kanals disable-auto-update Einstellung

    Terminalfenster
    npx @capgo/cli channel list
  4. Geräteüberschreibung: Prüfen Sie, ob das Gerät eine manuelle Überschreibung hat

    • Dashboard → Geräte → Gerät suchen → Kanal/Versionsnummer überprüfen
  1. Überprüfen Sie die Standardkanal: Stellen Sie sicher, dass der richtige Kanal in capacitor.config.ts
  2. Prüfen Sie die Bundle-Uploads: Überprüfen Sie, ob die Bundle auf den beabsichtigten Kanal hochgeladen wurde
  3. Inspektion der Mindestaktualisierungsversion: Bestätigen Sie --min-update-version (oder --auto-min-update-version) wurde festgelegt und der Kanal verwendet --disable-auto-update metadata
  1. Eilmaßnahme: Aktivieren Sie die betroffenen Geräte auf die sichere Bundle
    • Zurück zum Dashboard → Geräte → Masseauswahl → Versionsnummer setzen
  2. Langfristige Korrektur: Erstellen Sie kanalübergreifende Versionen und pflegen Sie separate Branchen
  3. Prävention: Testen Sie Updates immer auf repräsentativen Geräten vor der Rollout

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

AppFlow KonzeptCapgo ÄquivalentHinweise
Deploy-KanalCapgo KanalSelbiges Konzept, aber mächtiger
Native Version-Sperre--min-update-version / --auto-min-update-versionMehr fein abgestimmte Kontrolle
Kanal-PrioritätKanal-Vorrang (Übergeordnet → Cloud → Standard)Mehr transparenter Vorrang
Zielsystem für die BereitstellungKanal + semver-KontrolMehrere Strategien verfügbar
Produktionskanalproduction Kanal (oder beliebiger Name)Flexible Namensgebung
Git-basierte BereitstellungCLI Bundle-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 Versionszielsetzung
  4. Selbst-Hosting: Option, Ihren eigenen Update-Server mit gleicher Versionslogik zu betreiben
  1. Ihre AppFlow-Kanäle zuordnen zu Capgo Kanälen (üblicherweise 1:1)
  2. Setzen 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 Paketen mit --min-update-version (Kanal muss Metadatenstrategie verwenden)
  5. Überwachen der Versionenverteilung in Capgo Dashboard
// 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 Versionsunterscheidung über defaultChannel
  2. Semantische Versionsnummer: Verhindere Updates über Haupt-/Mino-/Patch-Grenzen
  3. Nativversionenbeschränkungen: Erforderliche Mindestversion für Bundles
  4. Verhindere automatische Downgrade: Nie liefern ältere Pakete an neueren native Versionen
  5. Geräteüberschreibungen: Manuelle Kontrolle für Tests und Zielsetzungen

Durch die Combination dieser Strategien können Sie AppFlow-Style-Update-Delivery mit noch mehr Flexibilität und Kontrolle erreichen. Wählen Sie die Ansatz, der am besten zu Ihrer App-Versionierung und -Veröffentlichungsworkflow passt.

Weitere Informationen zu bestimmten Funktionen:

Wenn Sie Version-Zielsetzung verwenden Version-Zielsetzung zum Planen der Kanalrouten und der schrittweisen Veröffentlichung, verbinden Sie es mit Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle zur Implementierungsdetail in Kanäle Zielgruppen-Testlösung zum Produktworkflow in Zielgruppen-Testlösung und zum Produktworkflow in Zielgruppen-Testlösung und zum Produktworkflow in Zielgruppen-Testlösung und Versionziel-Lösung für die Produktworkflow in Versionziel-Lösung.