Saltare al contenuto
Capgo - Costruisci, distribuisci e aggiorna Capacitor app Capgo

Canali

Channels are the core mechanism for managing app updates in Capgo. They allow you to control how and when your users receive updates, enabling features like A/B testing, staged rollouts, and platform-specific updates.

I canali sono il meccanismo di base per la gestione degli aggiornamenti dell'applicazione __CAPGO_KEEP_0__. Consentono di controllare come e quando gli utenti ricevono gli aggiornamenti, abilitando funzionalità come il testing A/B, i rilasci in fase di testing e gli aggiornamenti specifici per piattaforma.

Capitolo intitolato “Capire i canali”

Un canale rappresenta una traccia di distribuzione per gli aggiornamenti del tuo app. Ogni canale può essere configurato con regole e vincoli specifici.

  • Controllo del Pacchetto (versione)Controllo del pacchetto (versione)
  • Targetazione della piattaforma: Scegliere piattaforme specifiche (iOS/Android/Electron)
  • Politiche di Aggiornamento: Control how updates are delivered
  • Restrizioni del Dispositivo: Manage which devices can access updates

Opzioni di Configurazione del Canale

Sezione intitolata “Opzioni di Configurazione del Canale”
  • pubblico: Impostare come canale predefinito per i nuovi dispositivi.
  • disableAutoUpdateUnderNative: Prevenire gli aggiornamenti quando la versione dell'app nativa del dispositivo è più recente della versione stabile del canale.
  • disableAutoUpdate: Gestisci il comportamento dell'aggiornamento (major, minor, metadata, patch, o none).
  • aggiornaPackage: Controlla se i dispositivi scaricano un zip, un delta o entrambi (all, zip, delta, zip_from_builtin, o delta_from_builtin). Vedi Formato di download.
  • iOS/Android/Electron: Abilita o disabilita la consegna per piattaforma.
  • Consenti impostazioni dispositivo autoconfigurazione: Lascia che i dispositivi scegliano il canale.
  • Permetti all'emulatore, abilita_dispositivo, abilita_dev, abilita_produzione: Controlla quali tipi di dispositivo e build ricevono aggiornamenti.
  • Rilascio progressivo: Mantieni un bundle stabile mentre esponi un bundle di destinazione a un gruppo di utenti fedeli. Vedi Rilasci progressivi.

Buone Pratiche

Sezione intitolata “Pratiche Raccomandate”
  1. Pratiche MigliorativeSezione intitolata “Pratiche Migliorative”
  2. Canale di Testaggio: Utilizza più canali per il rilascio graduale degli aggiornamenti
  3. Separazione di piattaforma: Crea canali separati per iOS, Android e Electron quando necessario
  4. Controllo del pacchetto (versione): Utilizza semantica versioning per percorsi di aggiornamento chiari

Endpoint

Sezione intitolata “Endpoint”

POST

Sezione intitolata “POST”

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

Crea o aggiorna la configurazione di un canale.

Richiesta del corpo

Sezione intitolata “Richiesta del corpo”
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
  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 di rollout e di pausa automatica, il API accetta anche l'equivalente snake_case forma, come rollout_version o auto_pause_enabled. updatePackage accetta anche update_package. Se vengono forniti entrambi i formati, il valore in camelCase prevale. rollback è in camelCase solo.

Un obiettivo di rollout richiede un canale esistente. Deve avere un bundle stabile già assegnato o riceverne uno attraverso version nello stesso richiesta POST. rollback and promoteToStable sono azioni terminali; non combinarle tra loro.

Richiesta di esempio

Sottosezione intitolata “Richiesta di esempio”

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

Copia negli appunti
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

Sottosezione intitolata “Risposta di successo”
{
  "status": "ok"
}

POST è un upsert e restituisce solo lo stato. Effettua una richiesta GET per leggere la configurazione del canale risultante.

Limite di App Preview key

Sezione intitolata “Limite chiave anteprima app”

Per una anteprima di PR con privilegi minimi, autenticare questo endpoint con authorization: $CAPGO_API_KEY o capgkey: $CAPGO_API_KEY. Il x-api-key header non viene accettato dai canali API.

Un app_preview chiave può creare un nuovo canale di anteprima non pubblico. La creazione automatica assegna a quella chiave un vincolo di ciclo di vita a livello di canale per quel canale solo. Il ruolo non include channel.update_settings, quindi non può utilizzare POST per aggiornare un canale esistente, compreso un canale predefinito o principale.

Lasciare public impostato (o impostarlo su false) per i canali di anteprima di PR. Utilizzare bundle upload --channel Per la creazione e l'upload del flusso anziché trattare POST come un'anteprima generale del canale di aggiornamento.

Esegui GET

Sezione intitolata “Esegui GET”

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

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

Parametri di Query

Sezione intitolata “Parametri di Query”
  • app_id: Obbligatorio. L'ID del tuo'app
  • page: Facoltativo. Numero di pagina per la paginazione
  • channel: Facoltativo. Nome del canale specifico da recuperare

Esempi di Richiesta

Sezione intitolata “Esempi di Richiesta”
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"

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 È un atto di input e non viene restituito. Una distribuzione sospesa è rappresentata da un valore non nullo. rolloutPausedAt.

Esempio di risposta

Sezione intitolata “Esempio di risposta”
[
  {
    "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

Section titled “DELETE”

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

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

Corpo della richiesta

Sezione intitolata “Corpo della richiesta”
interface Channel {
  channel: string
  app_id: string
  delete_bundle?: boolean // also delete the linked bundle
}

Richiesta di esempio

Sezione intitolata “Richiesta di esempio”
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/

Risposta di successo

Sezione intitolata “Risposta di successo”
{
  "status": "ok"
}

Pulizia anteprima dell'app

Sezione intitolata “Pulizia anteprima dell'app”

With delete_bundle: true, un app_preview una chiave può pulire atomicamente solo un canale che ha creato e il suo bundle collegato, non condiviso. La chiave non riceve una bundle.delete permesso generale.

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/

Gestione degli Errori

Manutenzione degli errori

Sottosezione intitolata “Manutenzione degli errori”

// 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"
}

Casi d'uso comuni

Sezione intitolata “Casi d'uso comuni”
  1. Test di Beta
{
  "app_id": "com.example.app",
  "channel": "beta",
  "version": "1.2.0-beta",
  "public": false,
  "allow_emulator": true,
  "allow_dev": true
}
  1. Rilascio in 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
}

Continua da Canali

Section titled “Keep going from Channels”

Se stai utilizzando Canali per pianificare la routing dei canali e il rilascio in fasi, connettilo con Canali per i dettagli di implementazione nei canali, Canali per i dettagli di implementazione nei canali, Soluzione di Test Beta per il flusso di lavoro del prodotto nella Soluzione di Test Beta Soluzione di Targeting della Versione per il flusso di lavoro del prodotto nella Version Targeting Solution, e Capgo Environment Best Practices: Staging with One Mobile App ID Capgo Pratiche per l'ambiente Migliori: Staging con un ID di App Mobile