Canali
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
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.
Capire i Channel
Sezione intitolata “Capire i Channels”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
Opzioni di configurazione del Channel
Sezione intitolata “Opzioni di configurazione del Channel”- 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, onone).metadataè accettato come alias diversion_number. - updatePackage: Controlla se i dispositivi scaricano un zip, un delta o entrambi (
all,zip,delta,zip_from_builtin, odelta_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.
Best practice
Sezione “Best practice”- Canale di test: Mantieni un canale di test per la validazione interna
- Rilascio graduale: Usa più canali per un deployment graduale degli update
- Separazione delle piattaforme: Crea canali separati per iOS, Android ed Electron quando necessario
- Controllo del bundle (versione): Usa versionamento semantico per percorsi di aggiornamento chiari
Endpoint
Sezione intitolata “Endpoints”https://api.capgo.app/channel/
Crea o aggiorna la configurazione di un canale.
Corpo della richiesta
Sezione intitolata “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}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.
Esempio di richiesta
Sezione intitolata “Esempio di richiesta”Configura un rollout del 5% per un production channel esistente il cui bundle stabile è già impostato:
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/Risposta di successo
Sezione intitolata “Risposta di successo”{ "status": "ok"}POST esegue un upsert e restituisce solo lo status. Usa una richiesta GET per leggere la configurazione del channel risultante.
Limite della chiave di App Preview
Sezione intitolata “Limite della chiave di App Preview”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.
Parametri di query
Sezione intitolata “Parametri di query”app_id: Obbligatorio. L'ID della tua apppage: Opzionale. Numero di pagina per la paginazionechannel: Opzionale. Nome del channel specifico da recuperare
Esempi di richieste
Sezione intitolata “Esempi di richieste”# Get all channelscurl -H "authorization: your-api-key" \ "https://api.capgo.app/channel/?app_id=com.example.app"
# Get a specific channelcurl -H "authorization: your-api-key" \ "https://api.capgo.app/channel/?app_id=com.example.app&channel=production"
# Get the next pagecurl -H "authorization: your-api-key" \ "https://api.capgo.app/channel/?app_id=com.example.app&page=1"Tipo di risposta
Sezione intitolata “Tipo di risposta”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.
Risposta di esempio
Sezione intitolata “Risposta di esempio”[ { "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" }]ELIMINA
Sezione intitolata “DELETE”https://api.capgo.app/channel/
Elimina un canale. Tieni presente che ciò influenzerà tutti i dispositivi che utilizzano questo canale.
Corpo della richiesta
Sezione intitolata “Request Body”interface Channel { channel: string app_id: string delete_bundle?: boolean // also delete the linked bundle}Esempio di richiesta
Sezione intitolata “Esempio di richiesta”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/Risposta di successo
Sezione intitolata “Risposta di successo”{ "status": "ok"}Pulizia App Preview
Sezione intitolata “Pulizia App Preview”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.
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/Gestione degli errori
Sezione “Gestione degli errori”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": {}}Casi d'uso comuni
Sezione intitolata “Casi d'uso comuni”- Test beta
{ "app_id": "com.example.app", "channel": "beta", "version": "1.2.0-beta", "public": false, "allow_emulator": true, "allow_dev": true}- Rollout di produzione
{ "app_id": "com.example.app", "channel": "production", "version": "1.2.0", "public": true, "disableAutoUpdate": "minor"}- Aggiornamenti specifici per piattaforma
{ "app_id": "com.example.app", "channel": "ios-hotfix", "version": "1.2.1", "ios": true, "android": false}Continua da Channels
Sezione intitolata “Continua da Channels”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.