Canali
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Un canale di Aggiornamenti in tempo reale punta a una specifica versione del pacchetto JS del tuo app che verrà condivisa con qualsiasi dispositivo configurato per ascoltare quel canale per gli aggiornamenti. Quando installi il Capgo Aggiornamenti in tempo reale SDK nel tuo app, qualsiasi binario nativo configurato per quel canale controlla per gli aggiornamenti disponibili ogni volta che l'app viene avviata. Puoi modificare la versione a cui punta un canale in qualsiasi momento e puoi anche tornare a versioni precedenti se necessario.
Come un dispositivo sceglie un canale (precedenza)
Sezione intitolata “Come un dispositivo sceglie un canale (precedenza)”When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):
- Mappatura forzata del dispositivo (Dashboard) – Pianifica un ID dispositivo specifico su un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo sempre vince.
- Cloud override (per‑device) via Dashboard or API – Created when you change the device’s channel in the dashboard or via API. Use for QA users switching between feature / PR channels or to reproduce a user issue. Reinstalling the binary does not clear it; deleting the device entry does.
- Plugin
setChannel()canale locale – Creato quando l'app chiamasetChannel()e il backend verifica che il canale di destinazione consente l'assegnazione auto. Il canale selezionato viene memorizzato localmente su quel dispositivo, ha effetto immediatamente e non viene visualizzato nell'interfaccia di sovrapposizione del dispositivo.
- Capacitor config
defaultChannel(test build default) – Se presente incapacitor.config.*e non esiste alcun canale forzato/override/locale, l'app inizia su questo canale (ad esempio)beta,qa,pr-123Inteso per TestFlight / costruzioni interne affinché i tester si trovino automaticamente su un canale di anteprima. Le costruzioni di produzione lasciano spesso questo impostato su "nessuno". - Canale di default Cloud (percorso principale ~99% degli utenti) – Se segni un canale di default nel pannello di controllo, tutti gli utenti normali (nessun forzamento, nessuna sovrascrittura del pannello di controllo/API, nessun plugin locale, nessuna configurazione predefinita del canale) si attaccano qui. Modificare il canale di default consente di distribuire o ritirare immediatamente – senza nuovo binario. Se hai impostazioni predefinite per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo si attacca al canale predefinito che corrisponde alla sua piattaforma. Lasciare il canale di default cloud non impostato è consentito; in tal caso il dispositivo deve corrispondere ai passaggi 1-4 per ricevere aggiornamenti.
Pratica consigliata:
- Tratta 1-4 come layer di eccezione/test; quando imposti un canale di default, gli utenti reali dovrebbero flusso in esso. Se non scegli di impostarlo, sii deliberato su come gli utenti si attaccano (tipicamente tramite)
defaultChannelConfigura solo - nei binari che spedisci esplicitamente ai tester. Lasciare il campo vuoto mantiene la logica di produzione centralizzata nel pannello di controllo.
defaultChannelUtilizza - – Se presente in
setChannel()sparso in produzione—principalmente per le prove di qualità o i diagnostici mirati.
Se un canale è disabilitato per la piattaforma (iOS/Android/Electron toggles) quando altrimenti sarebbe stato scelto, il processo di selezione lo ignora e continua nella lista.
Riepilogo: Forza > Dashboard/API Override > Plugin
setChannel()canale locale > ConfigdefaultChannel> Impostazione predefinita Cloud.
Comportamento del Canale Predefinito
Sezione intitolata “Comportamento del Canale Predefinito”Impostare un'impostazione predefinita cloud è facoltativo, ma di solito serve come percorso di riserva per i nuovi dispositivi. Senza una di queste, solo i dispositivi che corrispondono alle mappature forzate, agli override o a una defaultChannel in Capacitor config riceveranno gli aggiornamenti. Quando scegli di segnalare i valori predefiniti, tieni presente:
- Impostazione predefinita singola (più comune) – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico valore predefinito; qualsiasi dispositivo senza override si attaccherà qui.
- Impostazioni predefinite specifiche per piattaforma – Se si suddividono i canali per piattaforma (ad esempio,
ios-productioncon solo iOS abilitato,android-productioncon solo Android abilitato, eelectron-productioncon solo Electron abilitato), segnalare ogni uno come predefinito per la sua piattaforma. Gli dispositivi iOS vanno al default iOS, gli Android vanno al default Android, e le applicazioni Electron vanno al default Electron.
Ricordate che il default cloud e defaultChannel entrambi occupano lo stesso livello di decisione. Se impostate un default cloud, non avete bisogno di duplicare il valore nella vostra __CAPGO_KEEP_0__ configurazione— lasciate capacitor.config.* both occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your Capacitor config—leave defaultChannel per i binari che intendete spedire ai tester o QA quando desiderate che inizino su un canale non di produzione anche se il default cloud è diverso. defaultChannel Potete modificare i default in qualsiasi momento nel pannello di controllo. Quando cambiate un default, i nuovi dispositivi seguono le nuove regole di routing immediatamente e gli dispositivi esistenti seguono le normali regole di precedenza la prossima volta che controllano.
Configurazione di un Canale
Sezione intitolata “Configurazione di un Canale”
– If you split channels by platform (for example,Durante l'acquisizione, crei il primo canale (la maggior parte delle squadre lo chiama “Produzione”), ma nulla è bloccato – puoi rinominare o cancellare qualsiasi canale in qualsiasi momento. Per aggiungere canali aggiuntivi in seguito:
- Vai alla sezione “Canali” del Capgo dashboard
- Clicca sul pulsante “Nuovo Canale”
- Inserisci un nome per il canale e clicca su “Crea”
I nomi dei canali possono essere qualsiasi cosa tu voglia. Una strategia comune è di corrispondere i canali alle tue fasi di sviluppo, ad esempio:
Development- per testare gli aggiornamenti live sui dispositivi locali o sugli emulatoriQA- per il tuo team di QA per verificare gli aggiornamenti prima della larga diffusioneStaging- per il test finale in un ambiente simile alla produzioneProduction- per la versione del tuo app che gli utenti finali ricevono dai negozi di app
Configurazione del Canale nell'App
Sezione intitolata “Configurazione del Canale nell'App”Con i canali creati, hai bisogno di configurare l'app per ascoltare il canale appropriato. In questo esempio, useremo il Development canale.
Apri il tuo capacitor.config.ts (o capacitor.config.json) file. Sotto la plugins sezione, opzionalmente impostare defaultChannel per build di test interni / QA). Per i build di produzione, preferisci ometterlo in modo che i dispositivi utilizzino il Cloud Default a meno che non venga esplicitamente sovrascritto.
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = { plugins: { CapacitorUpdater: { // For a QA/TestFlight build – testers start on the Development channel automatically. defaultChannel: 'Development', // Production builds usually omit this so users attach to the Cloud Default channel. }, },};Successivamente, costruisci il tuo app web e esegui npx cap sync per copiare il file di configurazione aggiornato nei tuoi progetti iOS, Android e Electron. Se salti questo passaggio di sincronizzazione, i tuoi progetti nativi continueranno ad utilizzare il canale con cui erano precedentemente configurati.
Opzioni e strategie dei canali
Sottosezione intitolata “Opzioni e strategie dei canali”I canali hanno diverse opzioni che controllano chi può ricevere aggiornamenti e come gli aggiornamenti sono consegnati. Le più importanti sono quelle elencate di seguito. Potete configurarle dall'app web, dal CLI, o dal Public API.
- Canale predefinito: Opzionalmente segnate i canali o le impostazioni specifiche del canale che i nuovi dispositivi si connettono. Vedere “Comportamento del canale predefinito” per gli scenari di routing.
- Filtri di piattaforma: Abilita o disabilita la consegna a
iOS,AndroidoElectrondispositivi per canale. - Disabilita l'auto downgrade sotto nativo: Impedisce di inviare un aggiornamento quando la versione nativa del dispositivo è più recente della bundle del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
- Consenti aggiornamenti di build di sviluppo: Consentire aggiornamenti a build di sviluppo (utile per la prova).
- Consenti dispositivi emulator: Consentire aggiornamenti a emulator/simulatore (utile per la prova).
- Consenti l'assegnazione di dispositivo auto: Lascia che l'app si passi a questo canale in esecuzione utilizzando
setChannel. Se disabilitato,setChannelfallirà per questo canale.
Rollout progressivi
Sezione intitolata “Rollout progressivi”Un canale può mantenere una bundle stabile mentre esporre gradualmente un obiettivo di rollout separato a un gruppo di dispositivi adesivi. Puoi fermare, riprendere, promuovere, tornare indietro e configurare una risposta di fallimento automatica senza cambiare il canale per tutti. Vedi Rilasci progressivi per il modello di consegna, flusso di lavoro del dashboard, API campi e CLI comandi.
Disabilita strategie di aggiornamento automatico
Sottosezione intitolata “Disabilita strategie di aggiornamento automatico”Utilizza questo per limitare i tipi di aggiornamenti che il canale consegnerà automaticamente. Opzioni:
- maggiore: Blocca un pacchetto di destinazione con una versione maggiore rispetto alla baseline nativa del dispositivo (
version_buildEsempio:1.2.3 -> 2.0.0è bloccato;1.2.3 -> 1.9.0è consentito. - minore: Blocca un pacchetto di destinazione con una versione maggiore o minore rispetto a
version_buildEsempio:1.2.3 -> 1.3.0è bloccato;1.2.3 -> 1.2.4è consentito. - patch: Modalità più rigorosa. Blocca qualsiasi modifica al numero maggiore, minore o di patch. Sono consentite solo le modifiche ai suffissi.
MAJOR.MINOR.PATCHrimane identico. Esempi:1.0.0-beta.1 -> 1.0.0-beta.2è consentito.1.0.0+build.1 -> 1.0.0+build.2è consentito.1.0.0 -> 1.0.1è bloccato. - metadata: Richiede una versione minima di aggiornamento di metadati su ogni bundle. Configurare tramite CLI usando
--min-update-versiono--auto-min-update-versionSe mancante, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non viene impostato. - nessuno: Consentire tutti gli aggiornamenti secondo la compatibilità di semver Queste strategie confrontano il bundle di destinazione del canale con la baseline nativa inviata come.
compatibilità di semver version_buildNon il bundle scaricato attualmente inviato come version_name.
Saperne di più dettagli e esempi in Disable updates strategy a /docs/cli/commands/#disable-updates-strategy.
Esempio (CLI):
# Block major updates on the Production channelnpx @capgo/cli@latest channel set production com.example.app \ --disable-auto-update major
# Allow devices to self-assign to the Beta channelnpx @capgo/cli@latest channel set beta com.example.app --self-assignUtilizzando setChannel() dal tuo App
Sottosezione intitolata “Utilizzando setChannel() dal tuo App”La setChannel() metodo consente al tuo app di cambiare canali in modo programmatico durante l'esecuzione. Ciò è particolarmente utile per:
- Menu di debug/QA dove gli tester possono cambiare tra canali
- Flussi di opzione per il programma beta
- Eseguimenti di flag di feature
- Scenari di test A/B
import { CapacitorUpdater } from '@capgo/capacitor-updater';
// Switch to the beta channelawait CapacitorUpdater.setChannel({ channel: 'beta' });
// Optionally trigger an immediate update check after switchingawait CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true});Assegnare un Bundle a un Canale
Sezione intitolata “Assegnare un Bundle a un Canale”Per distribuire un aggiornamento in tempo reale, è necessario caricare una nuova build del bundle JS e assegnarla a un canale. Ciò può essere fatto in un solo passo con il Capgo CLI:
npx @capgo/cli@latest bundle upload --channel=DevelopmentCiò caricherà i tuoi asset web costruiti e stabilirà il nuovo bundle come build attiva per il Development canale. Gli app configurati per ascoltare quel canale riceveranno l'aggiornamento la prossima volta che ne faranno richiesta.
È anche possibile assegnare le costruzioni ai canali dalla sezione “Bundle” del Capgo dashboard. Clicca sull'icona del menu accanto a una costruzione e seleziona “Assegna a Canale” per scegliere il canale per quella costruzione.
Versionamento dei Bundle e Canali
Sezione intitolata “Versionamento dei Bundle e Canali”È importante notare che i bundle in Capgo sono globali per il tuo'app, non specifici per canali individuali. Lo stesso bundle può essere assegnato a più canali.
Quando versioni i tuoi bundle, consigliamo di utilizzare Aggiornamenti di versione semantica con Capgo’s Tester di Semver e identificatori di rilascio pre-anteprima per edizioni specifiche del canale. Ad esempio, un rilascio beta potrebbe essere versionato come 1.2.3-beta.1.
In CI, se la versione locale era già caricata, utilizzare npx @capgo/cli@latest bundle upload --auto-bump (facoltativamente major, minor, patch/fix, metadata, o ai) in modo che CLI aumenti dal pacchetto collegato del canale fino a trovare un nome libero. Con ai, Workers AI inferisce il livello dal manifesto locale vs precedente delta (ricade su patch con nessuna versione precedente Capgo). Non è possibile combinarlo con --bundle. Vedi e il __CAPGO_KEEP_0__ di riferimento CLI reference.
Questa approccio ha diversi benefici:
- Comunica chiaramente la relazione tra le build.
1.2.3-beta.1è ovviamente una versione pre-rilascio di1.2.3. - Consente di riutilizzare i numeri di versione across canali, riducendo la confusione.
- Consente percorsi di rollback chiari. Se hai bisogno di tornare indietro da
1.2.3sai1.2.2è la versione stabile precedente.
Ecco un esempio di come potresti allineare le versioni dei tuoi bundle con un setup di canale tipico:
Developmentcanale:1.2.3-dev.1,1.2.3-dev.2ecc.QAcanale:1.2.3-qa.1,1.2.3-qa.2ecc.Stagingcanale:1.2.3-rc.1,1.2.3-rc.2, ecc.Productioncanale:1.2.3,1.2.4, ecc.
Utilizzo semver con identificatori di rilascio prenotificati è un approccio raccomandato, ma non è strettamente richiesto. La chiave è trovare uno schema di versioning che comunichi chiaramente le relazioni tra le tue build e si allinei con il processo di sviluppo del tuo team.
Ritornare indietro una Aggiornamento in Tempo Reale
Sezione intitolata “Ritornare indietro un Aggiornamento in Tempo Reale”Se hai distribuito un aggiornamento in tempo reale che introduce un bug o che altrimenti deve essere annullato, puoi facilmente tornare indietro a una versione precedente. Dalla sezione “Canali” della dashboard:
- Clicca il nome del canale che desideri tornare indietro
- Cerca la versione che desideri annullare e clicca l'icona della corona

- Conferma l'azione
Il costruito selezionato diventerà immediatamente la costruzione attiva per quel canale di nuovo. Le app riceveranno la versione ripristinata la prossima volta che controllano gli aggiornamenti.
Automazione delle distribuzioni
Sottosezione intitolata “Automazione delle distribuzioni”Per flussi di lavoro più avanzati, puoi automatizzare le tue distribuzioni di aggiornamento live come parte del tuo pipeline CI/CD. Integrando Capgo nel tuo processo di costruzione, puoi caricare automaticamente nuovi pacchetti e assegnarli ai canali ogni volta che puoi spingere su determinate branch o creare nuove versioni.
Esegui la consultazione dei Integrazione CI/CD docs to learn more about automating Capgo live updates.
documenti per imparare di più sull'automazione degli aggiornamenti live __CAPGO_KEEP_0__.
Previsualizzazioni PR con privilegi minimiSottosezione intitolata “Previsualizzazioni PR con privilegi minimi” Anteprima dell'app La chiave API viene utilizzata quando il CI necessita di una canale temporaneo per ogni richiesta di pull, ma non deve gestire i canali esistenti principali/definitivi. La chiave rimane legata all'organizzazione proprietaria e all'app selezionata; essa semplicemente non ha alcun ruolo organizzativo. Ogni canale di anteprima non pubblico che crea riceve la propria autorizzazione di ciclo di vita automatica, scoping per canale.
- Creare un amministratore di organizzazione una chiave sicura API limitata all'app di anteprima e selezionare Anteprima dell'appVedi Chiavi API.
- Utilizzare un canale unico e non pubblico come
pr-123Non passare--default,--self-assignopzioni di rilascio o--delete-linked-bundle-on-upload. - Carica e promuovi il bundle della PR in un comando, poi cancella il canale e il bundle di proprietà quando la PR si chiude:
APP_ID="com.example.app"PREVIEW_CHANNEL="pr-123"BUNDLE_VERSION="1.2.3-pr.123"
npx @capgo/cli@latest bundle upload "$APP_ID" \ --apikey "$CAPGO_PREVIEW_KEY" \ --path ./dist \ --channel "$PREVIEW_CHANNEL" \ --bundle "$BUNDLE_VERSION"
npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \ --apikey "$CAPGO_PREVIEW_KEY" \ --delete-bundle \ --success-if-not-foundbundle upload --channel crea un canale mancante, carica il pacchetto e lo promuove in un flusso unico. La pulizia è atomica e controllata dall'accesso: la chiave può cancellare solo un canale che ha creato e il suo pacchetto collegato, non condiviso. Non può cambiare, promuovere o cancellare un canale principale/di default esistente, un canale di un'altra chiave di anteprima o un pacchetto di un'altra chiave.
Se i revisori hanno bisogno di un QR code o di una URL di anteprima, un amministratore deve abilitare le anteprime una volta per l'app:
npx @capgo/cli@latest app set "$APP_ID" --previewnpx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --urlUna chiave di anteprima dell'app non può abilitare le anteprime da sola perché non ha la possibilità di modificare le impostazioni dell'app. In GitHub Actions, esegui i lavori di anteprima che contengono segreti su pull_request, non pull_request_target, e limitali a PRs con repository stesso con github.event.pull_request.head.repo.full_name == github.repository.
Distribuzione su un dispositivo
Sezione intitolata “Distribuzione su un dispositivo”Ora che hai capito i canali, sei pronto a iniziare a distribuire aggiornamenti live su dispositivi reali. Il processo base è:
- Installa il Capgo SDK nella tua app
- Configura l'app per ascoltare il tuo canale desiderato
- Carica un build e assegna il canale a cui appartiene
- Lancia l'app e attendi l'aggiornamento!
Per una guida dettagliata, consulta il Deploying Live Updates guide. Buon aggiornamento!
Utilizzo avanzato dei canali: segmentazione degli utenti
Sottosezione intitolata “Utilizzo avanzato dei canali: segmentazione degli utenti”I canali possono essere utilizzati per più di solo le fasi di sviluppo. Sono un potente strumento per la segmentazione degli utenti, che consente di attivare funzionalità come:
- Flag di feature per diversi livelli di utenti
- Test A/B
- Rollout graduale delle feature
- Programmi di testing beta
Impara a implementare questi casi d'uso avanzati nella nostra guida: Come segmentare gli utenti per piano e canali per le bandiere di feature e il testing A/B.
Continua da qui: canali
Sezione intitolata “Continua da qui: canali”Se stai utilizzando Canali Per pianificare la routing dei canali e il rilascio in fasi, connettilo con Canali Per i dettagli di implementazione in Canali, Per i dettagli di implementazione in Canali, Soluzione di testing beta Soluzione di testing beta per il workflow del prodotto nella Soluzione di Test Beta Versione Targeting Solution per il workflow del prodotto nella Soluzione di Targeting Versione, e Capgo Pratiche per l'ambiente Migliori: Staging con un ID App Mobile per il contesto pratico in Capgo Pratiche per l'ambiente Migliori: Staging con un ID App Mobile.