Canali

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

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 Bundle (versione): Specifica quale bundle (versione) ricevono gli utenti
• Targeting delle Piattaforme: Punta a piattaforme specifiche (iOS/Android/Electron)
• Policy di Aggiornamento: Controlla come vengono erogati gli update
• Restrizioni dei Dispositivi: Gestisci quali dispositivi possono accedere agli update

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, o none). metadata è accettato come alias di version_number.
• updatePackage: Controlla se i dispositivi scaricano un file zip, un delta o entrambi (all, zip, delta, zip_from_builtin, o delta_from_builtin). Vedi Formato download.
• ios/android/electron: Abilita o disabilita l'invio per piattaforma.
• consenti_impostazione_automatica_dispositivo: Let devices choose their channel.
• consenti_emulatore, consenti_dispositivo, consenti_dev, consenti_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

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 delle versioni dei Bundle: Usa versionamento semantico per percorsi di aggiornamento chiari

Endpoint

POST

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

Crea o aggiorna la configurazione di un channel.

Corpo della richiesta

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 la versione equivalente snake_case in questo formato, ad esempio: rollout_version o auto_pause_enabled. updatePackage accetta anche update_package. Se vengono forniti entrambi i formati, prevale il valore in camelCase. rollback è disponibile solo in camelCase.

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

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

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

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

Un app_preview la chiave può creare un nuovo canale preview non pubblico. La creazione assegna automaticamente a quella chiave un lifecycle binding limitato a quel canale. Il ruolo non include channel.update_settings, quindi non può usare POST per aggiornare un canale esistente, inclusi i canali default o main.

Lasciare public non impostato (o impostarlo a false) per i canali preview dei PR. Usa bundle upload --channel per il flusso di creazione e upload, invece di trattare la POST come un upsert generico del preview-channel.

GET

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

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

Parametri di query

• app_id: Obbligatorio. L'ID della tua app
• page: Opzionale. Numero di pagina per la paginazione
• channel: Opzionale. Nome del channel specifico da recuperare

Esempi di richieste

# 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

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 è uno shortcut di sola lettura e non viene restituito. Un rollout in pausa è rappresentato da un valore non nullo rolloutPausedAt.

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

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

Elimina un channel. Nota che questa azione influirà su tutti i dispositivi che utilizzano questo channel.

Corpo della richiesta

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

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

{
  "status": "ok"
}

Pulizia App Preview

Con delete_bundle: true, un app_preview la chiave può eliminare in modo atomico solo il canale creato e il relativo bundle non condiviso. La chiave non riceve permessi generali bundle.delete permessi.

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

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

1. Test beta

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

2. Rilascio in Produzione

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

3. Update Specifici per Piattaforma

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

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.