Saltare al contenuto
Capgo - Aggiornamenti in tempo reale per le app Capacitor Capgo

Canali

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

Capire i canali

Sezione intitolata “Capire i canali”

Un canale rappresenta una traccia di distribuzione per gli aggiornamenti dell'applicazione. Ogni canale può essere configurato con regole e vincoli specifici:

  • Controllo del pacchetto (versione): Specifica quale pacchetto (versione) gli utenti ricevono
  • Scegliere la piattaforma: Scegliere piattaforme specifiche (iOS/Android/Electron)
  • Politiche di Aggiornamento: Controllare come gli aggiornamenti vengono consegnati
  • Restrizioni del Dispositivo: Gestire quali dispositivi possono accedere agli aggiornamenti

Opzioni di Configurazione del Canale

: Sezione intitolata “Opzioni di Configurazione del Canale”
  • pubblico: Impostare come canale predefinito per i nuovi dispositivi.
  • disabilitaAggiornamentoSottoAppNativa: Prevenire gli aggiornamenti quando la versione dell'app nativa del dispositivo è più recente della versione stabile del canale.
  • disabilitaAggiornamentoAutomatico: Regola il comportamento dell'aggiornamento (major, minor, metadata, patch, o none).
  • aggiornaPacco: Regola se i dispositivi scaricano un zip, un delta o entrambi (all, zip, delta, zip_from_builtin, o delta_from_builtin). Vedi Pacco di aggiornamento.
  • ios/android/electron: Abilita o disabilita la consegna per piattaforma.
  • consentiImpostazioneDaParteDelDispositivo: Lascia che i dispositivi scelgano il canale.
  • abilita_emulatore, abilita_dispositivo, abilita_dev, abilita_prodControlla quali dispositivi e tipi di build ricevono aggiornamenti.
  • Rullo progressivoMantieni un bundle stabile mentre esponi un bundle di destinazione a un gruppo di utenti fedeli. Vedi Rulli progressivi.

Pratiche migliori

Sezione intitolata “Pratiche migliori”
  1. Canale di testingMantieni un canale di testing per la validazione interna
  2. Distribuzione in fase di staging: Utilizza più canali per il rilascio graduale dell'aggiornamento
  3. Separazione di piattaforma: Crea canali separati per iOS, Android e Electron quando necessario
  4. Controllo del pacchetto (versione): Utilizza versioning semantico per percorsi di aggiornamento chiari

Endpoint

Sezione intitolata “Endpoint”

POST

Sezione intitolata “POST”

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

Creare o aggiornare una configurazione di canale.

Corpo della richiesta

Sezione intitolata “Corpo della richiesta”
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, API accetta anche la forma equivalente snake_case o rollout_version o auto_pause_enabled. updatePackage anche accetta update_packageanche rollback anche accetta

se entrambe le forme sono fornite, il valore camelCase vince. version è solo camelCase. rollback E e promoteToStable Sono azioni terminali; non combinarle tra loro.

Esempio di richiesta

Sottosezione intitolata “Esempio di richiesta”

Configura un rollout del 5% per un canale esistente production Sottosezione intitolata “Configura un rollout del 5% per un canale esistente”

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/

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 chiave anteprima dell'applicazione

Sezione intitolata “Limite chiave anteprima dell'applicazione”

Per una anteprima di PR con privilegi minimi, autenticati questo endpoint con authorization: $CAPGO_API_KEY o capgkey: $CAPGO_API_KEYper creare una nuova canale di anteprima non pubblica. La creazione di un nuovo canale automaticamente assegna a quella chiave un binding di ciclo di vita a livello di canale per quel canale solo. Il ruolo non include x-api-key header is not accepted by the Channels API.

Lascia app_preview non impostato (o impostalo su channel.update_settingsper i canali di anteprima di PR. Utilizza

Il capo non è accettato dai canali __CAPGO_KEEP_0__. public Un falsepuò creare un nuovo canale di anteprima non pubblica. La creazione automatica assegna a quella chiave un binding di ciclo di vita a livello di canale per quel canale solo. Il ruolo non include bundle upload --channel Per la creazione e l'upload del flusso al posto di trattare POST come un preview-channel upsert generico.

GET

Sezione intitolata “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

Esempio di richieste
Fermata di 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

Esempio 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

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

Esempio di eliminazione

Esempio di richieste

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
}

Esempio di richiesta

Sezione intitolata “Esempio di richiesta”
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”

Con delete_bundle: true, una app_preview 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.

Fermata 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

Sezione intitolata “Gestione degli errori”

Scenari di errore comuni e le loro risposte:

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

Uso comune

Titolo della sezione “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. Avvio della produzione
{
  "app_id": "com.example.app",
  "channel": "production",
  "version": "1.2.0",
  "public": true,
  "disableAutoUpdate": "minor"
}
  1. Aggiornamenti specifici della piattaforma
{
  "app_id": "com.example.app",
  "channel": "ios-hotfix",
  "version": "1.2.1",
  "ios": true,
  "android": false
}

Continua da Canali

Se stai utilizzando

Canali Connettilo con per pianificare la routing dei canali e l'avvio in fase di test Canali per i dettagli di implementazione in Canali, Canali per i dettagli di implementazione in Canali, Soluzione di Test Beta per il flusso di lavoro del prodotto in Soluzione di Test Beta, Soluzione di Targeting della Versione per il flusso di lavoro del prodotto in Soluzione di Targeting della Versione, e Capgo Pratiche per l'ambiente Migliori: Staging con un ID di App Mobile Unico per il contesto pratico in Capgo Pratiche per l'ambiente Migliori: Staging con un ID di App Mobile Unico.