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

Kanäle

Kanäle sind die zentrale Mechanism zur Verwaltung von App-Updates in Capgo. Sie ermöglichen es Ihnen, die Art und Weise und das Zeitpunkt zu steuern, zu dem Ihre Benutzer Updates erhalten, wodurch Funktionen wie A/B-Test, geplante Rollouts und plattform-spezifische Updates ermöglicht 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:

  • Bündel (Version) Steuerung: Angibt, welches Bündel (Version) die Benutzer erhalten
  • Plattformzielgruppierung: Plattformen spezifisch anpassen (iOS/Android/Electron)
  • Update-Politiken: Steuern, wie Updates geliefert werden
  • Gerätebeschränkungen: Verwalten, welche Geräte Updates zugreifen können

Kanal-Konfigurations-Optionen

Abschnitt mit dem Titel “Kanal-Konfigurations-Optionen”
  • öffentlich: Als Standardkanal für neue Geräte festlegen.
  • disableAutoUpdateUnderNative: Updates verhindern, wenn die Geräte-App-Version neuere ist als die stabile Bundle des Kanals.
  • disableAutoUpdate: Steuere Aktualisierungsverhalten (major, minor, metadata, patch, oder none).
  • ios/android/electron: Aktivieren oder deaktivieren Sie die Lieferung nach Plattform.
  • allow_device_self_set: Lassen Sie die Geräte ihren Kanal wählen.
  • allow_emulator, allow_device, allow_dev, allow_prod: Steuern Sie, welche Geräte- und Build-Typen Updates erhalten.
  • Progressive rollout: Halten Sie ein stabiles Bundle bei gleichzeitiger Offenlegung eines Ziel-Bundles für eine stöckige Kohorte. Siehe Progressive Rollouts.

Best Practices

Abschnitt mit dem Titel “Best Practices”
  1. Testing Channel: Halten Sie einen Testkanal für interne Validierung
  2. Staged Rollout: Verwenden Sie mehrere Kanäle für die graduelle Bereitstellung von Updates
  3. Platform Separation: Erstellen Sie separate Kanäle für iOS, Android und Electron, wenn erforderlich
  4. Bundle (Version) Control: Verwenden Sie semantische Versionsnummer für klare Update-Pfade

Endpunkte

Abschnitt „Endpunkte“

POST

Abschnitt „POST“

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

Ein Kanalkonfiguration erstellen oder aktualisieren.

Anforderungskörper

Abschnitt „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 für Rollout und Auto-Pause akzeptiert API auch die entsprechende Form, wie z.B. snake_case Form 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 stabiles Bundle bereits zugewiesen haben oder eines durch version in derselben POST-Anfrage. rollback und promoteToStable sind terminale Aktionen; kombinieren Sie sie nicht miteinander.

Beispielanfrage

Abschnitt mit dem Titel „Beispielanfrage“

Eine 5-prozentige Rollout-Konfiguration für ein bestehendes production Kanal, dessen stabiles Bundle bereits festgelegt ist:

Terminalfenster
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 Einfügen und gibt nur seinen Status zurück. Machen Sie einen GET-Antrag, 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 von den Kanälen API nicht akzeptiert.

An app_preview Schlüssel kann eine neue nicht öffentliche Vorschaukanal erstellen. Die Erstellung gibt diesem Schlüssel automatisch eine Kanal-basierte Lebenszyklusbindung für diesen Kanal nur zu. channel.update_settingsDie Rolle umfasst nicht

, daher kann es nicht POST verwenden, um einen bestehenden Kanal zu aktualisieren, einschließlich eines bestehenden Standards- oder Hauptkanals. public Verlassen falseunbesetzt (oder setzen Sie es auf bundle upload --channel ) für PR-Vorschaukanäle. Verwenden Sie

für die Erstellung und Upload-Fließanweisung anstelle der Behandlung von POST als allgemeine Vorschaukanal-Überprüfung.

GET

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

Abschnitt mit dem Titel „GET“ channelAbrufen von Kanalinformationen. Gibt 50 Kanäle pro Seite zurück. Ohne channel, ist die Antwort ein Array. Mit

ist die Antwort ein Objekt für einen Kanal.

Abschnitt mit dem Titel “Query-Parameter”
  • app_id: Pflichtfeld. 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 nur eine Eingabe-Ersetzung und wird nicht zurückgegeben. Ein pausierter Rollout wird durch einen nicht-null-Wert dargestellt. 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"
  }
]

LÖSCHEN

Abschnitt mit dem Titel „LÖSCHEN”

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

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

Anfrage-Body

Abschnitt mit dem Titel „Anfrage-Body”
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-Aufräumung

Abschnitt mit dem Titel „App-Vorschau-Aufräumung“

Mit delete_bundle: true, eine app_preview Schlüssel kann die App-Vorschau eines von ihm erstellten Kanals und seines verbundenen, nicht geteilten Pakets atomisch aufräumen. Der Schlüssel erhält keine allgemeine bundle.delete Zugriffsrechte.

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

Abschnitt mit dem Titel „Fehlerbehandlung“

Häufige Fehler-Szenarien 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
}

Weitermachen von Kanälen

Abschnitt mit dem Titel „Weitermachen von Kanälen“

Wenn Sie "Kanäle" verwenden Kanäle um die Kanalroutenplanung und die schrittweise Rollout zu verwalten, verbinden Sie es mit Kanäle für die Implementierungsdetails in Kanäle Kanäle für die Implementierungsdetails in Kanäle Beta-Testlösung für das Produktworkflow in Beta-Testlösung Versionziel-Lösung für das Produktworkflow in Version Targeting Solution, und Capgo Umgebungsbest Practices: Staging mit einem Mobile App ID für den praktischen Kontext in Capgo Umgebungsbest Practices: Staging mit einem Mobile App ID.