Kanäle

Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.

Channels sind der Kernmechanismus für das App-Update-Management in Capgo. Mit ihnen steuerst du, wie und wann deine Nutzer Updates erhalten – ideal für A/B-Tests, Staged Rollouts oder plattformspezifische Updates.

Channels verstehen

Ein Channel ist ein Verteilungspfad für deine App-Updates. Jeder Channel lässt sich mit eigenen Regeln und Einschränkungen konfigurieren:

Bundle-Steuerung (Version): Festlegen, welches Bundle (Version) Nutzer erhalten
Plattform-Targeting: Bestimmte Plattformen gezielt ansteuern (iOS/Android/Electron)
Update-Richtlinien: Steuern, wie Updates ausgeliefert werden
Geräte-Einschränkungen: Verwalte, welche Geräte auf Updates zugreifen können

Channel-Konfigurationsoptionen

public: Als Standard-Channel für neue Geräte festlegen.
disableAutoUpdateUnderNative: Verhindert Updates, wenn die native App-Version des Geräts neuer ist als das stabile Bundle des Channels.
disableAutoUpdate: Update-Verhalten steuern (major, minor, patch, version_number, oder none). metadata wird akzeptiert als Alias für version_number.
updatePackage: Steuert, ob Geräte ein Zip, ein Delta oder beides herunterladen (all, zip, delta, zip_from_builtin, oder delta_from_builtin). Siehe Download-Format.
ios/android/electron: Aktiviert oder deaktiviert die Auslieferung pro Plattform.
Geräte-Selbstkonfiguration erlauben: Erlaubt Geräten, ihren eigenen Channel zu wählen.
Emulator erlauben, Gerät zulassen, allow_dev, allow_prod: Steuert, welche Geräte- und Build-Typen Updates erhalten.
Progressive Rollout: Behalte ein stabiles Bundle bei, während du ein Target-Bundle für eine feste Kohorte freigibst. Siehe Progressive Rollouts.

Best Practices

Test-Channel: Nutze einen Testing Channel für die interne Validierung
Staged Rollout: Nutze mehrere Channels für das schrittweise Deployment von Updates
Plattform-Trennung: Erstelle bei Bedarf separate Channels für iOS, Android und Electron
Bundle-Steuerung (Version): Nutze Semantic Versioning für eindeutige Update-Pfade

Endpoints

POST

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

Erstellt oder aktualisiert eine Channel-Konfiguration.

Request-Body

type DisableAutoUpdate = "major" | "minor" | "patch" | "version_number" | "metadata" | "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
  updatePackage?: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  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 Rollout- und Auto-Pause-Felder akzeptiert API auch die entsprechende snake_case Form, wie zum Beispiel rollout_version oder auto_pause_enabled. updatePackage akzeptiert auch update_package. Falls beide Formate angegeben werden, gewinnt der camelCase-Wert. rollback ist nur camelCase.

Ein Rollout-Target benötigt einen bestehenden Channel. Dieser muss bereits ein stabiles Bundle zugewiesen haben oder eines erhalten über version im selben POST-Request. rollback und promoteToStable sind finale Aktionen; kombiniere sie nicht miteinander.

Beispiel-Request

Konfiguriere einen 5% Rollout für einen bestehenden production Channel, dessen stabiles Bundle bereits gesetzt ist:

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/

Erfolgreiche Antwort

{
  "status": "ok"
}

POST fungiert als Upsert und gibt nur den Status zurück. Nutze einen GET-Request, um die resultierende Channel-Konfiguration zu lesen.

App Preview Key Boundary

Für eine PR-Preview nach dem Least-Privilege-Prinzip authentifiziere diesen Endpoint mit authorization: $CAPGO_API_KEY oder capgkey: $CAPGO_API_KEY. Die x-api-key Der Header wird vom Channels API nicht akzeptiert.

Ein app_preview kann einen neuen, nicht öffentlichen Preview-Channel erstellen. Bei der Erstellung erhält dieser Key automatisch ein Channel-scoped Lifecycle Binding nur für diesen Channel. Die Rolle beinhaltet nicht channel.update_settings, daher kann POST nicht verwendet werden, um einen bestehenden Channel zu aktualisieren, einschließlich eines bestehenden Default- oder Main-Channels.

Lassen Sie public leer (oder setzen Sie ihn auf false) für PR-Preview-Channels. Verwenden Sie bundle upload --channel für den Create- und Upload-Flow, anstatt POST als allgemeines Upsert für Preview-Channels zu behandeln.

GET

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

Channel-Informationen abrufen. Gibt 50 Channels pro Seite zurück. Ohne channel, ist die Antwort ein Array. Mit channel, ist die Antwort ein Channel-Objekt.

Query-Parameter

app_id: Erforderlich. Die ID deiner App
page: Optional. Seitenzahl für die Paginierung
channel: Optional. Spezifischer Channel-Name zum Abrufen

Beispiel-Requests

# 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"

Response-Typ

interface Channel {
  id: number
  created_at: string
  updated_at: string
  name: string
  app_id: string
  created_by: string
  public: boolean
  disableAutoUpdateUnderNative: boolean
  disableAutoUpdate: DisableAutoUpdate
  updatePackage: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  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 reiner Input-Shortcut und wird nicht zurückgegeben. Ein pausierter Rollout wird durch einen Non-Null-Wert dargestellt. rolloutPausedAt.

Beispiel-Response

[
  {
    "id": 1,
    "name": "production",
    "app_id": "com.example.app",
    "updatePackage": "all",
    "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

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

Löscht einen Channel. Beachte, dass dies alle Geräte betrifft, die diesen Channel nutzen.

Request-Body

interface Channel {
  channel: string
  app_id: string
  delete_bundle?: boolean // also delete the linked bundle
}

Beispiel-Request

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/

Erfolgreiche Antwort

{
  "status": "ok"
}

App Preview Bereinigung

Mit delete_bundle: true, ein app_preview Key kann atomar nur den von ihm erstellten Channel und dessen verknüpften, nicht geteilten Bundle bereinigen. Der Key erhält keine allgemeine bundle.delete Berechtigung.

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

Alle Fehler verwenden das Standard-Error-Format, das in der API Übersicht.

Häufige Fehlerszenarien und deren Antworten:

// The API key has no access to the app
{
  "error": "cannot_access_app",
  "message": "You can't access this app",
  "moreInfo": { "app_id": "com.example.app" }
}

// Invalid disableAutoUpdate value
{
  "error": "invalid_disable_auto_update",
  "message": "Disable auto update must be major, minor, patch, version_number, metadata, or none",
  "moreInfo": { "disableAutoUpdate": "always" }
}

// Rollout percentage out of range
{
  "error": "invalid_rollout_percentage",
  "message": "Rollout percentage must be between 0 and 100",
  "moreInfo": { "rolloutPercentage": 150 }
}

// DELETE without a channel name
{
  "error": "missing_channel_name",
  "message": "You must provide a channel name",
  "moreInfo": {}
}

Typische Anwendungsfälle

Beta-Testing

{
  "app_id": "com.example.app",
  "channel": "beta",
  "version": "1.2.0-beta",
  "public": false,
  "allow_emulator": true,
  "allow_dev": true
}

Production-Rollout

{
  "app_id": "com.example.app",
  "channel": "production",
  "version": "1.2.0",
  "public": true,
  "disableAutoUpdate": "minor"
}

Plattformspezifische Updates

{
  "app_id": "com.example.app",
  "channel": "ios-hotfix",
  "version": "1.2.1",
  "ios": true,
  "android": false
}

Weiterlesen zu Channels

Wenn Sie ... verwenden Kanäle nutzt, um das Channel-Routing und Staged Rollouts 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 Solution, Version-Targeting-Lösung für den Produkt-Workflow in der Version Targeting Solution, 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.