Kanäle

Neu bei Channels? Schau dir drei kurze Channel-Walkthroughs an, um Default Routing, Device Self-Assignment und Console Overrides live zu sehen.

Der @capgo/capacitor-updater Methoden setChannel() und unsetChannel() in diesem Guide werden nur auf Android und iOS unterstützt. Sie ändern das Channel-Routing in Browser-Previews nicht.

So wählt Capgo einen Channel aus (Priorität)

Wenn ein Device Capgo nach einem Update fragt, wird der verwendete Channel in dieser Reihenfolge festgelegt (höchste Priorität zuerst):

1. Forced Device Mapping: Wenn die Device ID explizit einem Channel zugewiesen wurde (das Geräte (Tab auf der Channel-Seite), dieser Channel gewinnt immer. Forced Mappings sind console/API Overrides. Capgo entfernt diese 90 Tage nach dem letzten Override-Schreibvorgang. Siehe Overrides aus Console und API laufen ab.
2. Cloud Override (Dashboard oder Public API): Das Ändern des Channels eines Geräts im Dashboard oder via Public API schreibt einen Override, der an diese Device ID gebunden ist. Eine Neuinstallation der App es nicht löscht ihn nicht; das Löschen des Overrides hingegen schon. Es gilt dieselbe 90-Tage-Aufbewahrungsfrist.
3. Plugin setChannel() (lokal): Bei aktuellen Plugin-Versionen setChannel() speichert den Channel auf dem Gerät nach der Backend-Validierung. Es ist kein Dashboard 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 explizit zu löschen.
4. Capacitor Konfiguration defaultChannel (Standard für Test-Builds): Für interne / Beta- / Test-Builds kannst du defaultChannel (Legacy-Key channel) in capacitor.config.* festlegen, damit Testgeräte in einem Pre-Release-Channel starten (z. B. beta, pr-123). Falls dieser fehlt, nutzt das Gerät den Cloud-Standard. Production-Builds lassen dies meist ungesetzt.
5. Cloud Default Channel (Hauptstrategie für ~99 % der User): Der primäre Produktions-Channel, auf den fast alle echten Nutzer gelangen. Jedes neue Gerät ohne Force, ohne Override und ohne lokale setChannel(), und ohne Konfiguration defaultChannel nutzt dies. Eine Änderung rollt (oder rollt zurück) für alle in Sekunden aus – ohne neues Binary.

Warum der Cloud-Standard der Hauptweg ist:

• Sofortiger Rollout oder Rollback, ohne native Binaries neu zu bauen oder erneut zu veröffentlichen.
• Ein Ort, um das Verhalten von iOS, Android und Electron zu steuern.
• Sicherer: Du kannst prüfen, ob Bundles existieren und die Settings korrekt sind, bevor du den Standard änderst.
• Auditierbare Änderungen (Teammitglieder sehen in der UI / in den Logs, wer was geändert hat). Designprinzip: Höhere Ebenen (Force / Override / Config) sind Ausnahmen (Debug für einzelne User, QA-Switching, Test-Build-Defaults). Normale User werden zum Cloud-Default geleitet.

Ändere den Cloud-Standard Channel beeinflusst neu normale Geräte, die:

• Nicht erzwungen werden
• Noch kein Cloud-Override vorhanden
• Keine App auf App-Ebene vorhanden defaultChannel definiert

Wenn ein Test-Build mit defaultChannel: 'beta' und du später den Cloud-Default auf production, Geräte, die mit starten, beta bleiben via Config dort, bis eine höher priorisierte Zuweisung greift oder ein Binary ohne defaultChannel. Das Löschen eines Force-, Cloud-Overrides oder einer lokalen setChannel() Zuweisung entfernt den Konfigurationswert nicht; dieser Fallback bleibt bis zum nächsten neuen Binary bestehen.

Geräte bleiben in ihrem aktuellen Channel, es sei denn, du:

• erzwingst einen Wechsel zu einem anderen Channel (via Console oder Public API).
• änderst den Cloud-Override im Dashboard oder im Public API.
• Rufe setChannel() (lokale Zuweisung bei aktuellen Plugin-Versionen).
• entfernst oder archivierst den aktuellen Channel (beim nächsten Check greifen dann wieder die Fallbacks gemäß der Priorisierung).
• wartest, bis ein Console/API Override nach 90 Tagen abläuft.
• Rufe unsetChannel() um eine lokale setChannel() Zuweisung zu löschen. Dies entfernt keinen Console/API Override oder eine app-konfigurierte defaultChannel; es gilt wieder die normale Priorität.
• Installiere die App neu, was bei älteren Updater-Versionen oder wenn App-Daten nicht wiederhergestellt werden, eine lokale Zuweisung löschen kann. Auf Android und iOS mit Updater 8.51.0 und neuer, persistDefaultChannelOnReinstall ist standardmäßig true, sodass wiederhergestellte App-Daten die lokale Auswahl nur beibehalten, solange diese Option aktiv ist, true. Console/API Overrides bleiben unberührt.

Ist ein Channel für eine Plattform deaktiviert (siehe iOS / Android / Electron Toggles) und wäre er sonst ausgewählt worden, überspringt die Auswahl diesen und fällt auf die nächste Regel zurück.

Hinweis: Das Setzen von defaultChannel erfordert eine Änderung des Binaries; nutze dies gezielt für Test/QA, nicht für die allgemeine Production-Steuerung.

Capacitor Konfigurationsbeispiel

capacitor.config.ts

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

Falls du den Standard im Dashboard später auf production änderst, werden Geräte auf anderen Channels (via config, override oder force) NICHT automatisch verschoben; nur neue Geräte (oder solche, bei denen du den override/force löschst) übernehmen die Änderung.

---

Channels verwalten

Schauen wir uns zuerst die Channels-Seite an. Du erreichst sie, indem du auf deine App klickst und dann auf den Channels-Tab klickst.

Einen Channel erstellen

Wie du siehst, gibt es unten rechts einen Plus-Button. (1 (im Bild) Ein Klick darauf öffnet ein Modal, in dem du einen neuen Channel erstellen kannst.

Nachdem du auf geklickt hast, Add sollte ein neuer Channel in der Liste erscheinen.

Was bedeutet „misconfigured“?

Manchmal ist die Konfiguration eines Channels ungültig. In diesem Fall erhältst du eine deutliche Warnung und die Misconfigured Spalte zeigt an: Yes für einen oder mehrere Channels. Mehr dazu erfährst du hier hier

Einen Channel löschen

Um einen Channel in der Web App zu löschen, öffne den Kanäle Tab für deine App und suche die Zeile für den Channel. In der Aktion Spalte auf das Trash-Icon und bestätige anschließend mit Löschen im Bestätigungsdialog.

Falls das Trash-Icon nicht sichtbar ist, hat dein Account keine channel.delete Berechtigung für diese App. Bitte einen Organisations- oder App-Admin, dir eine Rolle mit Löschrechten zuzuweisen, oder lösche den Channel mit einem API Key, der die nötigen Rechte besitzt:

npx @capgo/cli@latest channel delete <channel-name> <app-id>

Ein organisations- und app-gebundener App-Vorschau Key kann atomar nur den nicht-öffentlichen Preview-Channel und das damit erstellte Bundle löschen. channel delete <preview-channel> <app-id> --delete-bundleEr kann keinen bestehenden Default/Main-Channel, den Channel eines anderen Preview-Keys oder das Bundle eines anderen Keys ändern oder löschen. Siehe API Schlüssel für das Least-Privilege-Setup.

Einen Channel verwalten

Klicke auf den Channel-Namen, um die Channel-Seite zu öffnen. Dies ist eine vollständige Seite mit Tabs, kein Modal.

Channel-Tabs

• Dashboard: Adoption- und Installationsstatistiken des aktuellen Bundles für diesen Channel.
• Informationen: Channel-Einstellungen unten, plus Progressive Rollout und Test Update API.
• Geräte: Nur erzwungene Mappings aus der Console oder Public API. Es listet nicht jedes Gerät auf dem Channel auf und zeigt keine Geräte an, die setChannel(). Siehe Overrides aus Console und API laufen ab.
• Verlauf: Einstellungen und Bundle-Änderungen für diesen Channel.
• Vorschau: In-Browser- und Native-Vorschau des verknüpften Bundles. Aktiviere die Bundle-Vorschau in App-Informationen zuerst.

Informationseinstellungen

Bleibe auf dem Informationen Die Einstellungen erscheinen in dieser Reihenfolge:

Erstens, Standard-Download-Channel ist ein Status-Badge, kein Toggle. Aktiv bedeutet, dass dieser Channel der Cloud-Standard für neue Geräte ist. Klicke auf In App-Einstellungen verwalten um den Standard für App-Informationen. Für plattformspezifische Defaults (einen für iOS, einen für Android und einen für Electron) siehe denselben Abschnitt.

Zweitens die IOS Einstellung. Wenn dieser Wert auf false gesetzt ist, können iOS-Geräte keine Updates von diesem Channel herunterladen.

Drittens ist die Android Einstellung. Wenn dies auf false gesetzt ist, können Android-Geräte keine Updates von diesem Channel herunterladen.

Viertens ist die Electron Einstellung. Wenn dieser Wert auf false gesetzt ist, können Electron-Apps keine Updates von diesem Channel herunterladen.

Fünftens ist die Disable auto downgrade under native Einstellung. Wenn dies aktiviert ist, ist ein Downgrade von einer Native Build Version nicht mehr möglich. Das bedeutet, wenn du einen 1.2.0 Version im App Store oder Play Store hochgeladen hast und versuchst, die Channel-Version auf 1.1.0 zu setzen, wird das Update (Downgrade) fehlschlagen.

Sechstens ist die Disable auto updateEinstellung. Diese ist recht komplex; mehr dazu erfährst du in der hier

Siebtens ist die Download format Einstellung. Sie legt fest, ob Geräte ein komplettes ZIP, nur die geänderten Delta-Dateien oder die beste Kombination daraus herunterladen. Siehe Download-Format.

Achtens ist Allow development buildWenn dies wahr ist, können Development Builds Updates aus diesem Channel herunterladen. Andernfalls wird jede Update-Anfrage, die prod auf false gesetzt ist, abgelehnt. Dies ist vor allem für Testzwecke nützlich.

Neuntens ist Allow production build. Wenn dies auf false steht, erhalten Production-Builds (Store) keine Updates von diesem Channel. Aktivieren Sie dies für Channels, die echte Nutzer bedienen.

Zehntens ist der Allow EmulatorsIst dies falsch, lehnt Capgo alle Update-Anfragen von Emulatoren ab. Dies ist vor allem für Testzwecke nützlich.

Elftens ist Allow physical devices. Wenn dies auf false steht, lehnt Capgo Update-Anfragen von echten Smartphones und Tablets ab. Aktivieren Sie dies für Production-Channels.

Zwölftens ist Allow devices to self dissociate/associate. Wenn dies auf true steht, ist die setChannel Methode auf Android und iOS verfügbar. Wenn dies auf false steht und Sie versuchen, setChannel mit diesem Channel aufzurufen, wird der Aufruf fehlschlagen.

Test-Update API

At the bottom of the Informationen Tabs, klappe Test-Update API. Capgo zeigt einen curl-Befehl für /updates ein Testgerät auf diesem Channel an.

Aufgrund von Caching kann es bis zu 60 Sekunden dauern, bis Änderungen in API sichtbar sind. Falls der Channel nicht getestet werden kann, warnt dich die Console: Der Channel benötigt mindestens eine Plattform (iOS oder Android), Production Builds, physische Geräte und muss entweder der Standard-Download-Channel sein oder Device Self-Assignment erlauben.

Update-Benachrichtigung senden

Nachdem du das verknüpfte Bundle geändert hast, fragt die Console eventuell nach Update-Benachrichtigung senden. Das stellt einen Silent Push in die Warteschlange, sodass Geräte im Channel jetzt nach dem neuen Bundle suchen. Konfiguriere zuerst die Android- und iOS-Push-Credentials im Notifications-Tab der App.

Overrides aus Console und API laufen ab

Forced Mappings und Dashboard/Public API Channel-Overrides werden entfernt 90 Tagen ab nach dem letzten Override-Schreibvorgang. Der letzte Device Check-in setzt diese Frist nicht zurück. Um ein Assignment zu behalten, das diese Bereinigung übersteht, setze defaultChannel in deiner Capacitor Config (übersteht eine Neuinstallation, zum Ändern ist ein neues Binary nötig) oder rufe setChannel() aus einer Android- oder iOS-App mit @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, oder 8.0.0+ für die Major-Version deines Plugins. Diese Versionen speichern das Assignment lokal, sodass die 90-Tage-Bereinigung umgangen wird. Ältere Versionen schreiben einen Backend-Override, der derselben Bereinigung unterliegt. Auf Android und iOS mit Updater 8.51.0 und neuer, persistDefaultChannelOnReinstall ist standardmäßig true, sodass eine lokale Auswahl nur bei einer Neuinstallation erhalten bleibt, wenn das Betriebssystem die App-Daten wiederherstellt und persistDefaultChannelOnReinstall bleibt true. Eine Neuinstallation mit persistDefaultChannelOnReinstall: false kann diese lokale Auswahl löschen, selbst wenn die App-Daten wiederhergestellt werden. Nutze unsetChannel() , um diese lokale Auswahl explizit zu löschen.

Überschreibe die Aufbewahrungsfrist im Channel-Tab unter 'Devices'. Derselbe Hinweis erscheint, wenn du eine Device ID manuell auf den Channel erzwingst.

Dies ist unabhängig von der Aufbewahrung des Device-Inventars. Das Inventar entfernt Geräte, die sich seit 90 Tagen nicht mehr mit Capgo verbunden haben. Das Überschreiben der Bereinigung entfernt das Mapping, selbst wenn das Gerät noch aktiv ist. Details: Console- und API Overrides laufen nach 90 Tagen ab.

Download-Format

Öffne einen Channel und bleibe im Informationen . Download-Format steht in der Liste der Einstellungen unter „Auto-Update deaktivieren“.

Download-Format im Tab „Informationen“ des Channels. Neue Channels nutzen standardmäßig Zip + delta.

Mit dieser Einstellung legst du fest, was Capgo sendet, wenn ein Gerät in diesem Channel nach einem Update sucht. Lass Zip + Delta außer du musst einen bestimmten Typ erzwingen.

Label in der Konsole	CLI / API Wert	Download-Modus der Geräte
Zip + Delta (Standard)	all	Jedes Gerät erhält das beste unterstützte Paket. Geräte mit einer Plugin-Version, die Delta unterstützt, laden nur die geänderten Delta-Dateien herunter, sofern das Bundle diese enthält. Nur Geräte mit einer alten Plugin-Version ohne Delta-Support oder Bundles ohne Delta-Dateien greifen auf das vollständige Zip zurück.
Nur vollständiges Zip	zip	Jedes Gerät lädt das gesamte Bundle-Zip herunter, selbst wenn Delta-Dateien vorhanden sind.
Nur Delta	delta	Nur die geänderten Delta-Dateien. Geräte mit einer alten Plugin-Version ohne Delta-Support erhalten dennoch das vollständige Zip, falls das Bundle eines bereitstellt.
Vollständiges Zip nur ab Store-Build	zip_from_builtin	Nur vollständiges Zip, solange das Gerät noch auf dem Store-Build ist. Nach dem ersten live update liefert Capgo wieder Zip + Delta.
Delta nur ab Store-Build	delta_from_builtin	Nur Delta, solange das Gerät noch auf dem Store-Build ist. Nach dem ersten live update liefert Capgo wieder Zip + Delta.

Mit Zip + Delta, ist es normal, einige vollständige ZIP-Downloads zu sehen. Diese stammen von Geräten, die noch einen älteren Native Build mit einer Plugin-Version ohne Delta-Support ausführen (unter 5.10.0, 6.25.0, oder 7.0.35 für ihre Major-Version). Siehe Delta-Updates.

Der Store Build sind die Web-Assets, die im App Store oder Play Store Binary enthalten sind, bevor ein Capgo Update erfolgt. Nutze einen from store build only Modus, wenn das erste Update nach dem Store Build nur als Full ZIP oder nur als Delta erfolgen soll, spätere Updates aber beides nutzen können.

Capgo kombiniert keinen ZIP-only Channel mit einem Delta-only Bundle oder umgekehrt. Die Console, CLI und Channels API verweigert das Speichern und fordert dich auf, das fehlende Package hochzuladen oder den Modus zu wechseln.

Du kannst denselben Wert in CLI setzen. Der Channel muss bereits existieren:

npx @capgo/cli@latest channel set production com.example.app --update-package zip

Gültige Werte: all, zip, delta, zip_from_builtin, delta_from_builtin.

Progressive Rollouts

Der Channel Informationen Tab enthält einen Progressiver Rollout Abschnitt mit Rollout-Ziel und Stabiler Fallback, Rollout-Ziel ändern, Prozentsatz anwenden, und Aktionen Rollout abschließen, Rollout zurückrollen, Rollout aktivieren, Rollout deaktivieren, Rollout pausieren, und Rollout fortsetzen.

Die progressive Rollout-Steuerung erscheint oben im Tab „Channel Information“.

Lies Progressive Rollouts bevor du einen aktivierst. Dieser Guide behandelt das Upload-Routing (Auto (empfohlen) / Rollout-Ziel / Stable ersetzen; CLI --stable / API target: "stable" um zu überschreiben), das Dieser Channel nutzt progressive Rollouts bundle-link Dialog und einen sicheren Workflow mit Observe und Log-Insights.

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.