Vai al contenuto

Canali

I Channels sono il meccanismo centrale per gestire gli aggiornamenti delle app in Capgo. Ti permettono di controllare come e quando gli utenti ricevono gli aggiornamenti, abilitando funzionalità come A/B testing, rollout graduali e aggiornamenti specifici per piattaforma.

Un Channel rappresenta un canale di distribuzione per gli aggiornamenti della tua app. Ogni Channel può essere configurato con regole e vincoli specifici:

  • Controllo del bundle (versione): Specifica quale bundle (versione) ricevono gli utenti
  • Targeting per piattaforma: punta a piattaforme specifiche (iOS/Android/Electron)
  • Policy di aggiornamento: Control how updates are delivered
  • Restrizioni dispositivo: Gestisci quali dispositivi possono accedere agli update
  • pubblico: Impostato come channel predefinito per i nuovi dispositivi.
  • disableAutoUpdateUnderNative: Impedisce gli update quando la versione nativa dell'app del dispositivo è più recente del bundle stabile del channel.
  • disableAutoUpdate: Controlla il comportamento degli update (major, minor, patch, version_number, o none). metadata è accettato come alias di version_number.
  • updatePackage: Controlla se i dispositivi scaricano un zip, un delta o entrambi (all, zip, delta, zip_from_builtin, o delta_from_builtin). Vedi Formato download.
  • ios/android/electron: Abilita o disabilita la distribuzione per piattaforma.
  • allow_device_self_set: Consenti ai dispositivi di scegliere il canale.
  • allow_emulator, allow_device, allow_dev, allow_prod: Controlla quali dispositivi e tipi di build ricevono gli update.
  • Rollout progressivo: Mantieni un bundle stabile esponendo un bundle target a una coorte sticky. Vedi Rollout progressivi.
  1. Canale di test: Mantieni un canale di test per la validazione interna
  2. Rilascio graduale: Usa più canali per un deployment graduale degli update
  3. Separazione delle piattaforme: Crea canali separati per iOS, Android ed Electron quando necessario
  4. Controllo del bundle (versione): Usa versionamento semantico per percorsi di aggiornamento chiari

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

Crea o aggiorna la configurazione di un canale.

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
}

Per i campi rollout e auto-pause, API accetta anche l'equivalente snake_case in formato rollout_version oppure auto_pause_enabled. updatePackage accetta anche update_package. Se vengono forniti entrambi i formati, prevale il valore in camelCase. rollback è solo in camelCase.

Un target di rollout richiede un canale esistente. Deve già avere un bundle stabile assegnato o riceverne uno tramite version nella stessa richiesta POST. rollback e promoteToStable sono azioni terminali; non combinarle tra loro.

Configura un rollout del 5% per un production channel esistente il cui bundle stabile è già impostato:

Finestra del terminale
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/
{
"status": "ok"
}

POST esegue un upsert e restituisce solo lo status. Usa una richiesta GET per leggere la configurazione del channel risultante.

Per una preview PR con privilegi minimi, autentica questo endpoint con authorization: $CAPGO_API_KEY oppure capgkey: $CAPGO_API_KEY. L' x-api-key l'header non è accettato dai Channels API.

Un app_preview key può creare un nuovo canale di anteprima non pubblico. La creazione assegna automaticamente a quella key un binding lifecycle limitato a quel canale. Il ruolo non include channel.update_settings, quindi non può usare POST per aggiornare un canale esistente, compreso un canale default o main già esistente.

Lascia public non impostato (o impostalo su false) per i canali di anteprima PR. Usa bundle upload --channel per il flusso di creazione e upload, anziché trattare POST come un upsert generico del canale di anteprima.

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

Recupera le informazioni del canale. Restituisce 50 canali per pagina. Senza channel, la risposta è un array. Con channel, la risposta è un singolo oggetto channel.

  • app_id: Obbligatorio. L'ID della tua app
  • page: Opzionale. Numero di pagina per la paginazione
  • channel: Opzionale. Nome del channel specifico da recuperare
Finestra del terminale
# 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"
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 è una scorciatoia in sola lettura e non viene restituita. Un rollout in pausa è rappresentato da un valore non nullo rolloutPausedAt.

[
{
"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"
}
]

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

Elimina un canale. Tieni presente che ciò influenzerà tutti i dispositivi che utilizzano questo canale.

interface Channel {
channel: string
app_id: string
delete_bundle?: boolean // also delete the linked bundle
}
Finestra del terminale
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/
{
"status": "ok"
}

Con delete_bundle: true, un app_preview key può eseguire la pulizia atomica solo di un canale creato da essa e del bundle collegato non condiviso. La key non riceve informazioni generali bundle.delete permesso.

Finestra del terminale
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/

Tutti gli errori seguono il formato standard descritto nella Panoramica di API.

Scenari di errore comuni e relative risposte:

// 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": {}
}
  1. Test beta
{
"app_id": "com.example.app",
"channel": "beta",
"version": "1.2.0-beta",
"public": false,
"allow_emulator": true,
"allow_dev": true
}
  1. Rollout di produzione
{
"app_id": "com.example.app",
"channel": "production",
"version": "1.2.0",
"public": true,
"disableAutoUpdate": "minor"
}
  1. Aggiornamenti specifici per piattaforma
{
"app_id": "com.example.app",
"channel": "ios-hotfix",
"version": "1.2.1",
"ios": true,
"android": false
}

Se stai usando Canali per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow del prodotto nella Beta Testing Solution, Soluzione Version Targeting per il workflow del prodotto nella Version Targeting Solution, e Capgo Environment Best Practices: Staging con un unico Mobile App ID per il contesto pratico in Capgo Environment Best Practices: Staging con un unico Mobile App ID.