Zum Inhalt springen
Capgo - Live Updates für Capacitor-Apps Capgo

Kanäle

Kanäle sind die zentrale Mechanismatik zur Verwaltung von App-Updates in Capgo. Sie ermöglichen es Ihnen, zu kontrollieren, wie und wann Ihre Benutzer Updates erhalten, wodurch Funktionen wie A/B-Test, geplante Rollouts und plattform-spezifische Updates möglich werden.

Kanäle verstehen

Abschnitt mit dem Titel “Kanäle verstehen”

Ein Kanal stellt eine Verteilungsstrecke für Ihre App-Updates dar. Jeder Kanal kann mit spezifischen Regeln und Einschränkungen konfiguriert werden:

  • Paket (Version) Kontrolle: Bestimmen Sie, welches Paket (Version) die Benutzer erhalten
  • Plattformziel: Ziehen Sie bestimmte Plattformen (iOS/Android/Electron) an
  • Update-Politiken: Steuern Sie, wie Updates geliefert werden
  • Gerätebeschränkungen: Verwalten Sie, welche Geräte Zugriff auf Updates haben

Kanal-Konfigurationsoptionen

Abschnitt mit dem Titel „Kanal-Konfigurationsoptionen“
  • öffentlich: Legen Sie den Kanal als Standardkanal für neue Geräte fest.
  • disableAutoUpdateUnderNative: Verhindern Sie Updates, wenn die Version des native Geräte-Apps neuer ist als die stabile Bundle des Kanals.
  • disableAutoUpdate: Steuern Sie das Update-Verhalten (major, minor, metadata, patchoder none).
  • ios/android/electron: Aktivieren oder deaktivieren Sie die Lieferung nach Plattform.
  • zulassen_device_self_set: Lassen Sie die Geräte ihre Kanäle wählen.
  • zulassen_emulator, zulassen_device, zulassen_dev, zulassen_prod: Kontrollieren Sie, welche Geräte- und Build-Typen Updates erhalten.
  • Schrittweise Einführung: Halten Sie eine stabile Bundle, während ein Ziel-Bundle einer festen Kohorte zugänglich ist. Siehe Progressive rollouts.

Best Practices

Sicherheitsmaßnahmen
  1. Testkanal: Für interne Validierung einen Testkanal einrichten
  2. Stufenweise Bereitstellung: Mehrere Kanäle für die schrittweise Bereitstellung verwenden
  3. Plattformtrennung: Wenn nötig separate Kanäle für iOS, Android und Electron erstellen
  4. Paket (Version) Kontrolle: Semantische Versionsnummerierung verwenden Capgo Für klare Update-Pfade

Endpunkte

Sektion mit dem Titel „Endpunkte“

POST

Sektion mit dem Titel „POST“

https://api.capgo.app/channel/

Einen Kanalkonfiguration erstellen oder aktualisieren.

Anforderungskörper

Sektion mit dem Titel „Anforderungskörper“
type DisableAutoUpdate = "major" | "minor" | "metadata" | "patch" | "none"
type AutoPauseAction = "pause" | "rollback" | "notify"


interface ChannelSet {
  app_id: string
  channel: string
  version?: string | null // stable bundle name
  public?: boolean
  disableAutoUpdateUnderNative?: boolean
  disableAutoUpdate?: DisableAutoUpdate
  ios?: boolean
  android?: boolean
  electron?: boolean
  allow_device_self_set?: boolean
  allow_emulator?: boolean
  allow_device?: boolean
  allow_dev?: boolean
  allow_prod?: boolean


  // Progressive rollout (camelCase is preferred)
  rolloutVersion?: string | number | null // target bundle name or ID
  rolloutPercentage?: number // 0–100
  rolloutPercentageBps?: number // 0–10000; takes precedence when both are set
  rolloutEnabled?: boolean
  rolloutPaused?: boolean // input-only convenience flag
  rolloutPausedAt?: string | null // ISO timestamp or null
  rolloutPauseReason?: string | null
  rolloutCacheTtlSeconds?: number // 60–31536000
  rollback?: boolean
  promoteToStable?: boolean


  // Rollout auto-pause policy
  autoPauseEnabled?: boolean
  autoPauseWindowMinutes?: number
  autoPauseFailureRateBps?: number | null
  autoPauseConfidence?: number
  autoPauseMinAttempts?: number | null
  autoPauseMinFailures?: number | null
  autoPauseAction?: AutoPauseAction
  autoPauseCooldownMinutes?: number
}

Für die Felder Rollout und Auto-Pause akzeptiert API auch die entsprechende snake_case Form, wie rollout_version oder auto_pause_enabled. Wenn beide Formen bereitgestellt werden, gewinnt der camelCase-Wert. rollback ist nur camelCase.

Ein Rollout-Ziel erfordert ein bestehendes Kanal. Es muss ein stabiler Bundle bereits zugewiesen haben oder erhalten einen durch version in derselben POST-Anfrage. rollback und promoteToStable sind terminal; kombinieren Sie sie nicht miteinander.

Beispielanfrage

Abschnitt mit dem Titel “Beispielanfrage”

Konfigurieren Sie einen 5-Prozent-Rollout für ein bestehendes production Kanal, dessen stabiler Bundle bereits festgelegt ist:

Terminal-Fenster
curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "production",
    "rolloutVersion": "1.3.0",
    "rolloutPercentage": 5,
    "rolloutEnabled": true,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseMinAttempts": 100,
    "autoPauseAction": "pause"
  }' \
  https://api.capgo.app/channel/

Erfolgsantwort

Abschnitt mit dem Titel „Erfolgsantwort“
{
  "status": "ok"
}

POST ist ein Hoch- und Niederschwellenwert und gibt nur seinen Status zurück. Machen Sie einen GET-Anfordern, um die resultierende Kanal-Konfiguration zu lesen.

App-Vorschau-Schlüssel-Grenze

Abschnitt mit dem Titel „App-Vorschau-Schlüssel-Grenze“

Für eine geringstmögliche Berechtigung für die Vorschau einer PR authentifizieren Sie diesen Endpunkt mit authorization: $CAPGO_API_KEY oder capgkey: $CAPGO_API_KEY. Der x-api-key Header wird nicht von den Kanälen API akzeptiert.

Eine app_preview Kanalkennung kann einen neuen nicht öffentlichen Vorschaukanal erstellen. Die Erstellung gibt diesem Schlüssel automatisch eine kanal-spezifische Lebensdauerbundung für diesen Kanal nur zu. Die Rolle umfasst nicht channel.update_settingsKann nicht POST verwenden, um ein bestehendes Kanal zu aktualisieren, einschließlich eines bestehenden Standard- oder Hauptkanals.

Leave public unbelegt (oder setzen Sie es auf false) für Vorschaukanäle von Pull-Requests. bundle upload --channel Verwenden Sie

für die Erstellung und das Hochladen-Flow anstelle der Behandlung von POST als allgemeinen Vorschaukanal-Update.

GET

https://api.capgo.app/channel/

Abschnitt mit dem Titel “GET” channelRufen Sie Kanalinformationen ab. Gibt 50 Kanäle pro Seite zurück. Ohne channel, ist die Antwort ein Array. Mit

, ist die Antwort ein Kanalobjekt.

Abfrageparameter
  • app_id: Erforderlich. Die ID Ihrer App
  • page: Optional. Seitennummer für die Paginierung
  • channel: Optional. Spezifischer Kanalname zum Abrufen

Beispielanfragen

Abschnitt mit dem Titel “Beispielanfragen”
Terminalfenster
# Get all channels
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app"


# Get a specific channel
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&channel=production"


# Get the next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&page=1"

Antworttyp

Abschnitt mit dem Titel “Antworttyp”
interface Channel {
  id: number
  created_at: string
  updated_at: string
  name: string
  app_id: string
  created_by: string
  public: boolean
  disableAutoUpdateUnderNative: boolean
  disableAutoUpdate: DisableAutoUpdate
  allow_device_self_set: boolean
  allow_emulator: boolean
  allow_device: boolean
  allow_dev: boolean
  allow_prod: boolean
  version: { id: number, name: string } | null // stable bundle


  // These three response identifiers intentionally use snake_case.
  rollout_version: number | null
  rollout_id: string
  rollout_version_info: { id: number, name: string } | null


  rolloutPercentageBps: number
  rolloutEnabled: boolean
  rolloutPausedAt: string | null
  rolloutPauseReason: string | null
  rolloutCacheTtlSeconds: number
  autoPauseEnabled: boolean
  autoPauseWindowMinutes: number
  autoPauseFailureRateBps: number | null
  autoPauseConfidence: number
  autoPauseMinAttempts: number | null
  autoPauseMinFailures: number | null
  autoPauseAction: AutoPauseAction
  autoPauseCooldownMinutes: number
  autoPauseLastTriggeredAt: string | null
  autoPauseLastCheckedAt: string | null
}

rolloutPaused ist ein Eingabe-Only-Shortcut und wird nicht zurückgegeben. Ein pausierter Rollout wird durch eine nicht-Null-Wert rolloutPausedAt.

Beispielantwort

Abschnitt mit dem Titel „Beispielantwort“
[
  {
    "id": 1,
    "name": "production",
    "app_id": "com.example.app",
    "version": { "id": 1, "name": "1.2.0" },
    "rollout_version": 2,
    "rollout_id": "e60c19c9-2e65-4e0d-bc06-d1f5b4f96276",
    "rollout_version_info": { "id": 2, "name": "1.3.0" },
    "rolloutPercentageBps": 500,
    "rolloutEnabled": true,
    "rolloutPausedAt": null,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseAction": "pause"
  }
]

DELETE

Abschnitt mit dem Titel „DELETE“

https://api.capgo.app/channel/

Ein Kanal löschen. Beachten Sie, dass dies alle Geräte beeinflusen wird, die diesen Kanal verwenden.

Anforderungskörper

Abschnitt mit dem Titel „Anforderungskörper“
interface Channel {
  channel: string
  app_id: string
  delete_bundle?: boolean // also delete the linked bundle
}

Beispielanfrage

Abschnitt mit dem Titel „Beispielanfrage“
Terminalfenster
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "com.example.app",
    "channel": "beta"
  }' \
  https://api.capgo.app/channel/

Erfolgsantwort

Abschnitt mit dem Titel „Erfolgsantwort“
{
  "status": "ok"
}

App-Vorschau bereinigen

Abschnitt mit dem Titel „App-Vorschau bereinigen“

Mit einer delete_bundle: truean app_preview Schlüssel kann eine Kanal, die sie erstellt hat und deren verbundene, nicht geteilte Bundle, atomisch bereinigen. Der Schlüssel erhält keine allgemeine bundle.delete Zugriffsberechtigung.

Terminal-Fenster
curl -X DELETE \
  -H "capgkey: $CAPGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "pr-123",
    "delete_bundle": true
  }' \
  https://api.capgo.app/channel/

Fehlerbehandlung

Fehlerbehandlung

Häufige Fehler und ihre Antworten:

// Channel not found
{
  "error": "Channel not found",
  "status": "KO"
}


// Invalid bundle (version) format
{
  "error": "Invalid version format. Use semantic versioning",
  "status": "KO"
}


// Invalid update policy
{
  "error": "Invalid disableAutoUpdate value",
  "status": "KO"
}


// Permission denied
{
  "error": "Insufficient permissions to manage channels",
  "status": "KO"
}

Häufige Anwendungsfälle

Abschnitt mit dem Titel “Häufige Anwendungsfälle”
  1. Betaversionstest
{
  "app_id": "com.example.app",
  "channel": "beta",
  "version": "1.2.0-beta",
  "public": false,
  "allow_emulator": true,
  "allow_dev": true
}
  1. Produktionsstart
{
  "app_id": "com.example.app",
  "channel": "production",
  "version": "1.2.0",
  "public": true,
  "disableAutoUpdate": "minor"
}
  1. Plattform-spezifische Updates
{
  "app_id": "com.example.app",
  "channel": "ios-hotfix",
  "version": "1.2.1",
  "ios": true,
  "android": false
}

Fortsetzung von Channels

Bleib weiterhin an Kanälen dran

Wenn Sie " Kanäle" für die Planung der Kanalsteuerung und der schrittweisen Veröffentlichung verwenden, verbinden Sie sie mit " 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 Beta-Testlösung, " Version-Zielsystemlösung für das Produktworkflow in Version-Zielsystemlösung Capgo Umgebungsbest Practices: Staging mit einem Mobilgerät-App-ID für den praktischen Kontext in Capgo Umgebungsbest Practices: Staging mit einem Mobilgerät-App-ID.