Kanäle

Ein Live Update Channel verweist auf einen bestimmten JS-Bundle-Build deiner App, der an alle Geräte ausgeliefert wird, die so konfiguriert sind, dass sie auf diesem Channel auf Updates lauschen. Wenn du installiere das Capgo Live Updates SDK In deiner App prüft jede native Binary, die für diesen Channel konfiguriert ist, beim App-Start auf verfügbare Updates. Du kannst den Build, auf den ein Channel zeigt, jederzeit ändern und bei Bedarf auch auf vorherige Builds zurückrollen.

Kurz gesagt: für Staging und Produktion in einer Capacitor-App, erstelle einen staging und einen production Channel in Capgo, lade jedes Bundle hoch zu staging teste es zuerst, dann stufe dasselbe Bundle hoch zu production.

Channels in der Praxis

Betrachte einen Channel als einen benannten Pointer auf ein Update: production can serve your released app while beta bedient Tester. Diese drei kurzen Videos zeigen, wie ein Gerät auf einem Channel landet. Jedes Video hat optionale Hintergrundmusik und keinen Kommentar; die Erklärungen unten beschreiben dieselben Schritte.

1. Den Standard-Channel nutzen

Ein Gerät, das ein v1.1.0 fragt Capgo nach einem Update. Ohne Device-Zuweisung oder in der App konfigurierten Channel prüft Capgo den Cloud-Default, production, und gibt dessen v1.2.0 Bundle. Die dev und staging Channels behalten ihre eigenen Bundles, ohne dieses Gerät zu beeinflussen.

Video des Standard-Channels herunterladen (MP4).

Setze deinen Production-Default in App-Informationen. Normale Produktions-Builds können defaultChannel ungesetzt lassen, damit du dieses Routing über Capgo verwalten kannst.

2. Ein Gerät einen Channel wählen lassen

Diese Anleitung verwendet setChannel() und unsetChannel() von @capgo/capacitor-updater auf Android und iOS; diese Methoden werden im Browser nicht unterstützt. Sie nutzt das lokale Channel-Verhalten, das in updater 5.34.0+, 6.34.0+, 7.34.0+, oder 8.0.0+ für die Major-Version deines Plugins verfügbar ist. Ältere Versionen schrieben stattdessen ein Backend-Override; diese Zuweisungen folgen den Konsole und API Override-Retention-Regeln.

Ein Tester aktiviert Beta-Updates in deiner App. Deine App ruft CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true }). Capgo prüft, ob beta ermöglicht das Self-Assignment von Geräten; das Plugin speichert die Auswahl dann lokal für zukünftige Update-Checks. Andere Geräte behalten ihr bestehendes Routing.

Video zur Geräte-Selbstzuweisung herunterladen (MP4).

Aktivieren Geräten erlauben, sich selbst zu trennen/zu verbinden auf dem Zielkanal, bevor du sie nutzt setChannel(). Diese lokale Auswahl erzeugt kein Console-Override. Auf Android und iOS mit Updater 8.51.0 und neuer, persistDefaultChannelOnReinstall ist standardmäßig true, sodass die Auswahl eine Neuinstallation nur überlebt, wenn das Betriebssystem die App-Daten wiederherstellt und persistDefaultChannelOnReinstall bleibt true. Aufrufen unsetChannel() um die lokale Auswahl zu löschen; Console- und API Overrides folgen weiterhin der unten aufgeführten Priorität.

3. Ein Gerät über die Console zuweisen

Öffnen Sie in der Capgo-Konsole Apps, wählen Sie Ihre App aus und öffnen Geräte, und wählen Sie ein Gerät aus. Ändern Sie dessen Channel-Override zu dev. Capgo leitet dieses Gerät nun an dev, während der Cloud-Standard der App bei production.

Video zum Geräte-Override in der Konsole herunterladen (MP4).

Nutze ein Override für gezieltes Testen oder Support. Es hat Vorrang vor dem lokalen Channel des Geräts und dem Cloud-Default, sofern kein erzwungenes Mapping vorliegt. Console- und API-Overrides verfallen 90 Tage nach dem letzten Schreiben eines Overrides.

Bereit zum Ausprobieren? Erstelle einen Channel in der Console, dann lade ein Bundle hoch damit es ausgeliefert werden kann.

Channels gewährleisten keine Vertraulichkeit

Channels steuern, wer Updates erhält, nicht die Geheimhaltung von Bundles. Auch wenn ein Channel privat ist oder Self-Assignment deaktiviert ist, sollte jedes unverschlüsselte Bundle, das auf Capgo hochgeladen wird, weiterhin als öffentliches Asset gelten, das an Clients ausgeliefert wird. Verschlüsselung schützt den Auslieferungspfad und die Authentizität von Updates, aber ausgelieferte Bundles lassen sich mit genügend Aufwand trotzdem aus der verteilten App reverse engineeren, da der Public Key Teil des Clients ist. Siehe Live Update-Verschlüsselung für Details.

Wie ein Gerät einen Channel auswählt (Priorität)

Wenn ein Gerät nach einem Update sucht, entscheidet Capgo in dieser strikten Reihenfolge (höchste Priorität zuerst), welchen Channel es verwendet:

1. Erzwungenes Device-Mapping (Dashboard) – Manuelles Pinning einer bestimmten Device ID auf einen Channel. Nutze das für dringendes Debugging oder kontrollierte Tests mit einem einzelnen echten Nutzer. Dies hat immer Vorrang. Capgo entfernt das Mapping 90 Tage nach dem letzten Override-Schreibvorgang. Siehe Console- und API Overrides laufen nach 90 Tagen ab.
2. Cloud-Override (pro Gerät) via Dashboard oder API – Wird erstellt, wenn du den Channel des Geräts im Dashboard oder via API änderst. Nutze dies für QA-User, die zwischen Feature- oder PR-Channels wechseln, oder um Nutzerprobleme zu reproduzieren. Eine Neuinstallation der Binary löscht dies nicht; das Löschen des Device-Overrides hingegen schon. Es gilt dieselbe 90-Tage-Frist.
3. Plugin setChannel() lokaler Channel – Wird erstellt, wenn die App aufruft setChannel() und das Backend validiert, dass der Ziel-Channel eine Selbstzuweisung erlaubt. Der gewählte Channel wird lokal auf dem Gerät gespeichert, wirkt sofort und wird nicht in der Device Override UI angezeigt.

Sofortiger Channel-Wechsel mit setChannel()

Ab Plugin-Version 5.34.0, 6.34.0, 7.34.0 oder 8.0.0 (abhängig von deiner Major-Version), setChannel() funktioniert anders: Es kontaktiert das Backend, um zu validieren, dass der Channel erlaubt ist (prüft, ob Self-Assignment für diesen Channel aktiviert ist), und speichert den Channel dann lokal auf dem Gerät als defaultChannel. Das bedeutet, der neue Channel wird sofort beim nächsten Update-Check aktiv – ohne auf die Replikation zu warten.

Bisher wurde setChannel() die Channel-Überschreibung in der Backend-Datenbank gespeichert (wie bei Dashboard- oder API-Änderungen), wodurch Geräte auf die Datenreplikation warten mussten (bis zu 2 Minuten), bevor der neue Channel erkannt wurde. Das neue Verhalten liest nur vom Backend (zur Validierung) und speichert lokal, wodurch Channel-Wechsel sofort erfolgen.

Da setChannel() nur lokal ist, erstellt es es nicht einen Device Override-Eintrag im Capgo-Dashboard. Die Device Override UI zeigt nur Overrides an, die im Dashboard oder über die öffentliche API erstellt wurden.

Hinweis: Selbst wenn ein Channel nach dem lokalen Setzen als nicht zulässig markiert wird, validiert das Backend den Channel weiterhin bei Update-Checks, sodass die Sicherheit gewahrt bleibt.

Wichtig: Wenn Channel-Änderungen über das Dashboard oder API vorgenommen werden, gibt es eine Replikationsverzögerung von bis zu 2 Minuten, bis alle Edge-Server die Änderung widerspiegeln. Für einen sofortigen Channel-Wechsel verwenden Sie setChannel() aus Ihrer App code – es validiert mit dem Backend und setzt den Channel dann lokal, damit er sofort wirkt.

4. Capacitor Konfiguration defaultChannel (Standard für Test-Builds) – Falls vorhanden in capacitor.config.* und kein force/override/local Channel existiert, startet die App auf diesem Channel (z. B. beta, qa, pr-123). Gedacht für TestFlight / interne Builds, damit Tester automatisch auf einem Pre-Release-Channel landen. Produktions-Builds lassen dieses Feld in der Regel leer.
5. Cloud Default Channel (Hauptpfad, ~99 % der Nutzer) – Wenn Sie einen Standard-Channel im Dashboard markieren, werden alle regulären Endnutzer (ohne Force, ohne Dashboard/API-Override, ohne lokalen Plugin-Channel, ohne config defaultChannel) hier angehängt. Ändern Sie ihn, um sofort auszurollen oder zurückzurollen – ohne neues Binary. Wenn Sie plattformspezifische Standards haben (z. B. einer nur für iOS, einer nur für Android, einer nur für Electron), landet jedes Gerät auf dem Standard, der zu seiner Plattform passt. Den Cloud-Standard leer zu lassen ist erlaubt; in diesem Fall muss das Gerät über die Schritte 1–4 übereinstimmen, um Updates zu erhalten.

Best Practice:

• Behandeln Sie 1–4 als Ausnahmen-/Testebenen; wenn Sie einen Cloud-Standard setzen, sollten echte Nutzer in diesen fließen. Wenn Sie sich dagegen entscheiden, einen zu setzen, entscheiden Sie bewusst, wie Nutzer angehängt werden (typischerweise über defaultChannel in der config oder per-Gerät-Overrides).
• Konfigurieren Sie nur defaultChannel in Binaries, die Sie explizit an Tester ausliefern. Wenn Sie es leer lassen, bleibt die Produktionslogik zentral im Dashboard.
• Nutzt setChannel() sparsam in der Produktion – hauptsächlich für QA oder gezielte Diagnosen.

Wenn ein Channel für die Plattform (iOS/Android/Electron-Toggles) deaktiviert ist, wenn er sonst ausgewählt würde, überspringt der Auswahlprozess ihn und fährt in der Liste fort.

Zusammenfassung: Force > Dashboard/API Override > Plugin setChannel() lokaler Channel > Config defaultChannel > Cloud-Standard.

Console- und API Overrides laufen nach 90 Tagen ab

Erzwungene Mappings sowie Dashboard- oder öffentliche API-Channel-Overrides werden als gerätespezifische Zuweisungen in Capgo gespeichert. Ein Cleanup-Job löscht diese Zuweisungen. 90 Tage nach dem letzten Override-Schreibvorgang. Das Prüfen auf ein Update setzt diesen Timer nicht zurück. Nur das erneute Schreiben des Overrides (oder das manuelle Löschen) ändert den Zeitstempel.

Das ist nicht dasselbe wie die Aufbewahrung des Device-InventarsDas Inventory entfernt Geräte, die 90 Tage lang nicht mit Capgo verbunden waren. Ein Override-Cleanup entfernt das Mapping auch dann, wenn das Gerät noch aktiv ist.

Für eine Zuweisung, die durch diesen Cleanup nicht entfernt wird:

• Setzen Sie defaultChannel in einem capacitor.config.* (übersteht eine Neuinstallation; erfordert später ein neues natives Binary).
• Rufe setChannel() aus der App. Ab Plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 ist diese Zuweisung lokal und wird nicht durch diesen Cleanup entfernt. Auf Android und iOS mit Updater 8.51.0 oder neuer, persistDefaultChannelOnReinstall ist standardmäßig true, sodass die Zuweisung eine Neuinstallation nur übersteht, wenn das Betriebssystem die App-Daten wiederherstellt und persistDefaultChannelOnReinstall bleibt true. Nutze unsetChannel() , um sie explizit zu löschen.

Der Channel Geräte Der Channel-Tab und die Device-Override-UI listen nur Console- und Public-API-Assignments auf. Sie führen nicht alle Geräte im Channel auf und führen keine lokalen setChannel() Assignments auf.

Auf dem Tab „Devices“ des Channels die Aufbewahrungsfrist überschreiben.

Standard-Channel-Verhalten

Ein Cloud-Default ist optional, dient aber meist als Catch-all-Pfad für neue Geräte. Ohne einen solchen erhalten nur Geräte Updates, die zu Forced Mappings, Overrides oder einem Eintrag defaultChannel in der Capacitor-Config passen. Wenn du Defaults festlegst, beachte diese Muster:

• Einzelner Default (am häufigsten) – Wenn ein Channel iOS, Android und Electron aktiviert hat, wird er zum einzigen Default; alle Geräte ohne Overrides werden hier angehängt.
• Plattformspezifische Defaults – Wenn du Channels nach Plattform trennst (zum Beispiel, ios-production nur mit iOS aktiviert, android-production nur mit Android aktiviert, und electron-production nur mit Electron aktiviert), markiere jeden als Default für seine Plattform. iOS-Geräte nutzen den iOS-Default, Android-Geräte den Android-Default und Electron-Apps den Electron-Default.

Denk daran, dass der Cloud-Default und defaultChannel in einem capacitor.config.* beide besetzen dieselbe Entscheidungsebene. Wenn du einen Cloud-Standard setzt, musst du den Wert nicht in deiner Capacitor-Konfiguration duplizieren – lass defaultChannel für Produktions-Builds leer. Reserviere defaultChannel für Binaries, die du absichtlich an Tester oder QA schickst, wenn sie auf einem Nicht-Produktions-Channel starten sollen, selbst wenn der Cloud-Standard anders ist.

Du kannst Standards jederzeit im Dashboard ändern. Öffne den Channel, dann In App-Einstellungen verwalten, die Sie weiterleitet zu App-Informationenführt. Der Standard ist kein Schalter mehr auf der Channel-Seite. Wenn du einen Standard änderst, folgen neue Geräte sofort der neuen Routing-Logik, und bestehende Geräte folgen den normalen Präzedenzregeln beim nächsten Check-in.

Channel einrichten

Während des Onboarding erstellst du den ersten Channel (die meisten Teams nennen ihn „Production“), aber nichts ist festgelegt – du kannst jeden Channel jederzeit umbenennen oder löschen. Um später zusätzliche Channels hinzuzufügen:

1. Gehe im Capgo-Dashboard zum Bereich „Channels“
2. Klicke auf den Button „New Channel“
3. Gib einen Namen für den Channel ein und klicke auf „Create“

Channel-Namen können frei gewählt werden. Eine gängige Strategie ist es, die Channels an deine Entwicklungsphasen anzupassen, wie zum Beispiel:

• Development - zum Testen von Live Updates auf lokalen Geräten oder Emulatoren
• QA - für dein QA-Team, um Updates vor dem breiteren Release zu prüfen
• Staging - für finale Tests in einer produktionsnahen Umgebung
• Production - für die Version deiner App, die Endnutzer aus den App Stores erhalten

Channel in deiner App konfigurieren

Sobald deine Channels erstellt sind, musst du deine App so konfigurieren, dass sie auf den entsprechenden Channel hört. In diesem Beispiel verwenden wir den Development Channel.

Öffne deine capacitor.config.ts (oder capacitor.config.json) Datei. Unter dem plugins Abschnitt optional festlegen defaultChannel für Test-Builds (internal / QA). Bei Production-Builds besser weglassen, damit Geräte den Cloud Default nutzen, sofern er nicht explizit überschrieben wird.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

Baue als Nächstes deine Web-App und führe npx cap sync aus, um die aktualisierte Config-Datei in deine iOS-, Android- und Electron-Projekte zu kopieren. Wenn du diesen Sync-Schritt überspringst, nutzen deine nativen Projekte weiterhin den Channel, der zuvor konfiguriert war.

Achtung

Reihenfolge der Channel-Auswahl: Force > Dashboard/API Device-Override > Plugin setChannel() lokaler Channel > Config defaultChannel > Cloud-Standard.

Nutzt defaultChannel nur in Test-/Internal-Builds; in Production weglassen, damit Nutzer dem Cloud Default (falls gesetzt) folgen, statt das Routing in der nativen Config zu duplizieren.

Du kannst ein Gerät weiterhin erzwingen (pinnen) oder später ein Override anwenden – beides überschreibt den Config-Wert sofort.

Channel-Namen sind case-sensitive.

Channel-Optionen und -Strategien

Channels haben mehrere Optionen, die steuern, wer Updates erhalten kann und wie sie ausgeliefert werden. Die wichtigsten sind unten aufgeführt. Du kannst sie in der Web-App, der CLI oder der Public API konfigurieren.

• Standard-Channel: Optional den Channel oder plattformspezifische Channels markieren, an die neue Geräte angehängt werden. In der Konsole befindet sich dies unter App-Informationen (In App-Einstellungen verwalten aus der Kanal-Seite). Siehe „Standardverhalten des Kanals“ für Routing-Szenarien.
• Plattformfilter: Aktivieren oder deaktivieren Sie die Auslieferung an iOS, Android, oder Electron Geräte pro Kanal.
• Automatisches Downgrade unter native deaktivieren: Verhindert das Senden eines Updates, wenn die native App-Version des Geräts neuer ist als das Bundle des Kanals (z. B. Gerät auf 1.2.3, während der Kanal 1.2.2 hat).
• Entwickler-Builds erlauben: Erlaubt Updates für Entwickler-Builds (nützlich für Tests). CLI: --dev / --no-dev.
• Produktions-Builds erlauben: Erlaubt Updates für Produktions- (Store-)Builds. Für Kanäle, die echte Nutzer bedienen, sollte dies aktiviert bleiben. CLI: --prod / --no-prod.
• Emulator-Geräte erlauben: Erlaubt Updates für Emulatoren/Simulatoren (nützlich für Tests). CLI: --emulator / --no-emulator.
• Physische Geräte erlauben: Erlaubt Updates für echte Smartphones und Tablets. Für Produktionskanäle sollte dies aktiviert bleiben. CLI: --device / --no-device.
• Selbstzuweisung des Geräts erlauben: Ermöglicht der App, zur Laufzeit auf diesen Kanal umzuschalten, indem sie setChannelverwendet. Wenn deaktiviert, setChannel wird für diesen Channel fehlschlagen. CLI: --self-assign / --no-self-assign.
• Download-Format: Wähle, ob Geräte eine vollständige Zip-Datei, nur die geänderten Delta-Dateien oder das Beste aus beidem herunterladen (all, zip, delta, zip_from_builtin, delta_from_builtin). Siehe Download-Format für das Dropdown in der Konsole und wann welcher Modus sinnvoll ist.

Progressive Rollouts

Ein Channel kann ein stabiles Bundle beibehalten und gleichzeitig schrittweise ein separates Rollout-Ziel für eine feste Gerätegruppe freigeben. Du kannst pausieren, fortsetzen, promoten, Rollbacks durchführen und eine automatische Fehlerreaktion konfigurieren, ohne den Channel für alle umzustellen. Siehe Progressive Rollouts für das Delivery-Modell, den Dashboard-Workflow, API Felder und CLI Befehle.

Auto-Update-Strategien deaktivieren

Nutze dies, um einzuschränken, welche Arten von Updates der Channel automatisch ausliefert. Optionen:

• major: Blockiert ein Target-Bundle, dessen Major-Version höher ist als die native Baseline des Geräts (version_build). Beispiel: 1.2.3 -> 2.0.0 wird blockiert; 1.2.3 -> 1.9.0 ist erlaubt.
• minor: Blockiert ein Target-Bundle, dessen Major- oder Minor-Version von version_build. Beispiel: 1.2.3 -> 1.3.0 wird blockiert; 1.2.3 -> 1.2.4 ist erlaubt.
• patch: Strengster Modus. Blockiert jede Änderung an Major-, Minor- oder Patch-Nummer. Nur Suffix-Änderungen sind erlaubt, während MAJOR.MINOR.PATCH identisch bleibt. Beispiele: 1.0.0-beta.1 -> 1.0.0-beta.2 ist erlaubt, 1.0.0+build.1 -> 1.0.0+build.2 ist erlaubt, 1.0.0 -> 1.0.1 wird blockiert.
• Metadaten: Fordert eine Mindest-Update-Version in den Metadaten jedes Bundles. Konfiguration über CLI mit --min-update-version oder --auto-min-update-version. Fehlt es, wird der Channel als fehlerhaft konfiguriert markiert und Updates werden abgelehnt, bis er gesetzt ist.
• none: Erlaubt alle Updates gemäß semver-Kompatibilität.

Diese Strategien vergleichen das Ziel-Bundle des Channels mit der nativen Baseline, die als version_build, nicht das aktuell heruntergeladene Bundle, das als version_name.

Weitere Details und Beispiele findest du unter Disable updates strategy in /docs/cli/commands/#disable-updates-strategy.

Beispiel (CLI). Der Channel muss bereits existieren (channel set erstellt ihn nicht):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

setChannel() in deiner App nutzen

Der @capgo/capacitor-updater Methode setChannel() ermöglicht es deiner Android- oder iOS-App, Channels zur Laufzeit programmatisch zu wechseln. Das ist besonders nützlich für:

• QA/Debug-Menüs, in denen Tester zwischen Channels wechseln können
• Opt-in-Flows für Beta-Programme
• Implementierungen von Feature Flags
• A/B-Testing-Szenarien

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });

// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

So funktioniert setChannel() (v5.34.0+ / v6.34.0+ / v7.34.0+ / v8.0.0+)

Wenn setChannel() heißt:

1. Backend-Validierung (nur lesend): Eine Anfrage wird an das Capgo-Backend gesendet, um zu validieren, ob der Channel erlaubt ist (Prüfung der Self-Assignment-Berechtigungen)
2. Update des lokalen Speichers: Wenn die Validierung erfolgreich ist, wird der Channel im lokalen Speicher des Geräts gespeichert als defaultChannel
3. Sofortige Wirkung: Der nächste Update-Check verwendet den neuen Channel sofort (kein Warten auf Replikation)

Warum das wichtig ist: In älteren Versionen setChannel() hat das Channel-Override in der Backend-Datenbank gespeichert (wie bei Änderungen im Dashboard oder über API). Geräte mussten auf die Backend-Replikation warten (bis zu 2 Minuten), bevor die Channel-Änderung wirksam wurde. Jetzt setChannel() liest nur aus dem Backend (zur Validierung) und speichert lokal, wodurch Channel-Wechsel sofort erfolgen.

Sichtbarkeit im Dashboard: Ein mit dem Plugin gesetzter Channel führt nicht dazu, dass das Gerät als Device Override in der Capgo-UI angezeigt wird. Dort werden nur Channel-Zuweisungen aufgelistet, die über das Dashboard oder die öffentliche API erstellt wurden. Verwende das Dashboard oder API, wenn du ein für Admins sichtbares Override brauchst.

Sicherheitshinweis: Auch wenn sich die Berechtigungen eines Channels nach dem lokalen Setzen ändern (z. B. wenn die Selbstzuweisung deaktiviert wird), validiert das Backend den Channel weiterhin bei Update-Prüfungen, damit die Sicherheit erhalten bleibt.

Vergleich der Methoden für Channel-Änderungen:

Methode	Effektzeit	Speicherort	In der Device Override UI sichtbar	Läuft ab	Anwendungsfall
setChannel() vom Plugin	Sofort	Nur auf dem Gerät (lokal)	Nein	Kein automatischer Ablauf; löschen mit unsetChannel() (Neuinstallation kann es beibehalten)	In-App-Channel-Wechsel durch User
Geräte-Override im Dashboard	Bis zu 2 Min.	Backend-Datenbank	Ja	90 Tage nach dem letzten Override-Write	Admin-initiierte Änderungen für bestimmte Geräte
API Channel-Zuweisung	Bis zu 2 Min.	Backend-Datenbank	Ja	90 Tage nach dem letzten Override-Write	Automatisierte Backend-Integrationen

Für die beste User Experience beim Erstellen von Channel-Switching-UIs solltest du immer das Plugin nutzen setChannel() Methode.

Mindestversionen für rein lokales Channel-Switching: 5.34.0, 6.34.0, 7.34.0, oder 8.0.0 (abhängig von deiner Major-Version). Jede Minor-Version entspricht dem gleichen Feature-Set über alle Major-Versionen hinweg (z. B. enthält X.34.0 dieselben Features, egal ob X 5, 6, 7 oder 8 ist). Siehe Plugin-Installation für Version-Tags.

Einem Channel ein Bundle zuweisen

Um ein live update bereitzustellen, müssen Sie einen neuen JS-Bundle-Build hochladen und einem Channel zuweisen. Das geht in einem Schritt mit dem Capgo CLI:

npx @capgo/cli@latest bundle upload --channel=Development

Dadurch werden Ihre gebauten Web-Assets hochgeladen und das neue Bundle als aktiver Build für den Development channel. Alle Apps, die auf diesen channel lauschen, erhalten das Update beim nächsten Check.

Sie können Builds auch über den Abschnitt „Bundles“ im Capgo-Dashboard Channels zuweisen. Klicken Sie auf das Menüsymbol neben einem Build und wählen Sie „Channel zuweisen“, um den Channel für diesen Build auszuwählen.

Bundle-Versioning und Channels

Wichtig: Bundles in Capgo sind global für deine App und nicht an einzelne Kanäle gebunden. Dasselbe Bundle kann mehreren Kanälen zugewiesen werden.

Bei der Versionierung deiner Bundles empfehlen wir die Verwendung von semantischer Versionierung mit dem Semver-Tester von Capgo und Pre-Release-Identifiern für kanal-spezifische Builds. Ein Beta-Release könnte beispielsweise als 1.2.3-beta.1.

In CI: Falls die lokale Version bereits hochgeladen wurde, nutze npx @capgo/cli@latest bundle upload --auto-bump (optional major, minor, patch/fix, metadata, oder ai), damit CLI die Version des dem Kanal zugeordneten Bundles hochskaliert, bis ein freier Name gefunden ist. Mit aischätzt Workers AI den Level anhand des Deltas zwischen lokalem und vorherigem Manifest (Fallback auf patch ohne vorherige Capgo-Version). Sie können es nicht mit --bundle. Siehe CI/CD-Integration und CLI Referenz.

Dieser Ansatz bietet mehrere Vorteile:

• Er verdeutlicht die Beziehung zwischen den Builds. 1.2.3-beta.1 ist offensichtlich ein Pre-Release von 1.2.3.
• Er ermöglicht die Wiederverwendung von Versionsnummern über Channels hinweg und reduziert so Verwirrung.
• Er ermöglicht klare Rollback-Pfade. Wenn Sie zurückrollen müssen von 1.2.3, wissen Sie, 1.2.2 ist die vorherige stabile Version.

Hier ist ein Beispiel, wie Sie Ihre Bundle-Versionen mit einer typischen Channel-Konfiguration abstimmen können:

• Development Channel: 1.2.3-dev.1, 1.2.3-dev.2, usw.
• QA Channel: 1.2.3-qa.1, 1.2.3-qa.2, usw.
• Staging Channel: 1.2.3-rc.1, 1.2.3-rc.2, usw.
• Production Channel: 1.2.3, 1.2.4, usw.

Verwendung SemVer mit Pre-Release-Identifiern ist ein empfohlener Ansatz, aber nicht zwingend erforderlich. Wichtig ist ein Versionierungsschema, das die Beziehungen zwischen deinen Builds klar kommuniziert und zu deinem Team-Workflow passt.

Rollback eines Live Update

Wenn du einen live update deployst, der einen Bug enthält oder anderweitig zurückgesetzt werden muss, kannst du einfach zu einem vorherigen Build zurückrollen. Im Dashboard unter „Channels“:

1. Klicke auf den Namen des Channels, den du zurückrollen möchtest
2. Finde den Build, zu dem du zurückkehren möchtest, und klicke auf das Kronen-Icon
3. Aktion bestätigen

Der ausgewählte Build wird sofort wieder zum aktiven Build für diesen Channel. Apps erhalten die zurückgerollte Version beim nächsten Update-Check.

Deployments automatisieren

Für fortgeschrittene Workflows kannst du deine live update Deployments als Teil deiner CI/CD-Pipeline automatisieren. Durch die Integration von Capgo in deinen Build-Prozess kannst du neue Bundles automatisch hochladen und ihnen Channels zuweisen, sobald du in bestimmte Branches pushst oder neue Releases erstellst.

Schau dir die CI/CD-Integration Docs an, um mehr über die Automatisierung von Capgo Live Updates zu erfahren.

Least-privilege PR Previews

Verwende einen App-Vorschau API Key, wenn die CI pro Pull Request einen temporären Channel benötigt, aber keine bestehenden Main/Default-Channels verwalten darf. Der Key bleibt an die jeweilige Organisation und die ausgewählte App gebunden; er hat lediglich keine organisationsweite Rolle. Jeder nicht öffentliche Preview-Channel, den er anlegt, erhält eine eigene, automatisch auf den Channel begrenzte Lifecycle-Berechtigung.

1. Lass einen Administrator der Organisation einen sicheren API Key erstellen, der auf die Preview-App beschränkt ist, und wähle App-Vorschau. Siehe API Schlüssel.
2. Nutze einen eindeutigen, nicht öffentlichen Channel wie pr-123. Übergeben Sie nicht --default, --self-assign, Rollout-Optionen oder --delete-linked-bundle-on-upload.
3. Bundle der PR in einem Befehl hochladen und promoten, danach den zugehörigen Channel und das Bundle löschen, wenn die PR geschlossen wird:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel erstellt einen fehlenden Channel, lädt das Bundle hoch und promove es in einem einzigen Flow. Die Bereinigung ist atomar und ownership-basiert: Der Key kann nur einen Channel löschen, den er selbst erstellt hat, sowie das damit verknüpfte, nicht geteilte Bundle. Er kann keinen bestehenden main/default-Channel, den Channel eines anderen Preview-Keys oder das Bundle eines anderen Keys ändern, promoten oder löschen.

Wenn Reviewer einen QR code oder eine Preview-URL benötigen, muss ein Administrator Previews einmalig für die App aktivieren:

npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

Ein App Preview Key kann keine Previews selbst aktivieren, da er keine Berechtigung für App-Einstellungen hat. Führe in GitHub Actions Preview-Jobs mit Secrets auf pull_request, nicht pull_request_target, und beschränke sie auf PRs im selben Repository mit github.event.pull_request.head.repo.full_name == github.repository.

Deployment auf ein Gerät

Nachdem du Channels verstanden hast, kannst du mit dem Deployment von Live Updates auf echte Geräte beginnen. Der Prozess sieht so aus:

1. Installiere das Capgo SDK in deiner App
2. Konfiguriere die App so, dass sie auf deinen gewünschten Channel hört
3. Lade einen Build hoch und weise ihn diesem Channel zu
4. Starte die App und warte auf das Update!

Für eine detaillierte Anleitung schau dir die Live Updates Deployment Guide. Viel Spaß beim Updaten!

Erweiterte Channel-Nutzung: User-Segmentierung

Channels können für mehr als nur Entwicklungsphasen genutzt werden. Sie sind ein starkes Tool für User-Segmentierung und ermöglichen Features wie:

• Feature Flags für verschiedene User-Tiers
• A/B-Testing
• Schrittweise Feature-Rollouts
• Beta-Testprogramme

Erfahre in unserem Guide, wie du diese fortgeschrittenen Use Cases implementierst: So segmentierst du User nach Plan und Channels für Feature Flags und A/B-Testing.

Weiter von Channels

Wenn du es nutzt Kanäle 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, Beta-Testing-Lösung für den Produkt-Workflow in der Beta-Testing-Lösung, Version-Targeting-Lösung für den Produkt-Workflow in der Version-Targeting-Lösung und Capgo Environment Best Practices: Staging mit einer Mobile App ID für den praktischen Kontext in Capgo Environment Best Practices: Staging mit einer Mobile App ID.