Canali
Copia un avviso 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 costruita del pacchetto JS del tuo'applicazione 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'applicazione, qualsiasi binario nativo configurato su quel canale controlla per gli aggiornamenti disponibili ogni volta che l'applicazione viene avviata. Puoi modificare la versione a cui punta quel 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)”Quando un dispositivo controlla un aggiornamento, Capgo decide quale canale utilizzare in questo ordine rigoroso (priorità più alta per prima):
- Impegno forzato del dispositivo (Dashboard) – Pianifica un ID dispositivo specifico su un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo vince sempre. Capgo rimuove la mappatura dopo 90 giorni dall'ultima scrittura di override. Vedi Console e override API scadono dopo 90 giorni.
- Override Cloud (per dispositivo) via Dashboard o API – Creato quando cambia il canale del dispositivo nel dashboard o via API. Utilizza per utenti QA che passano tra canali di feature / PR o per riprodurre un problema di utente. Ristallando il binario non si cancella; eliminando l'override del dispositivo si cancella. La stessa conservazione di 90 giorni si applica.
- Plugin
setChannel()canale locale – Creato quando l'app chiamasetChannel()e il backend verifica che il canale di destinazione consente l'assegnazione auto.
- Capacitor config
defaultChannel(costruzione di test predefinita) – Se presente incapacitor.config.*e non esiste un canale forzato/sovrascrittura locale, l'app inizia su questo canale (ad esempiobeta,qa,pr-123Inteso per le costruzioni di TestFlight / interne, in modo che i tester cadano su un canale di anteprima automaticamente. Le costruzioni di produzione lasciano questo impostato di solito. - Canale predefinito Cloud (percorso principale ~99% degli utenti) – Se segni un canale predefinito 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. Cambialo per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai dei valori predefiniti specifici per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo si attacca al valore predefinito che corrisponde alla sua piattaforma. Lasciare il canale predefinito cloud non impostato è consentito; in quel caso il dispositivo deve corrispondere ai passaggi 1–4 per ricevere aggiornamenti.
Pratica consigliata:
- Trovare un modo per trattare 1–4 come livelli di eccezione/test; quando si imposta un canale predefinito cloud, gli utenti reali dovrebbero flusso in esso. Se non si sceglie di impostarlo, sia deliberato su come gli utenti si attaccano (di solito via
defaultChannelconfigurare in config o sovrascrivere per dispositivo). - Sono abilitati solo la configurazione
defaultChannelconfigurare in binari che spedisci esplicitamente ai tester. Lasciare in bianco mantiene la logica di produzione centralizzata nel dashboard. - Usare
setChannel()usare con parsimonia 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 Cloud predefinita.
Il console e API sovrascrivono scadono dopo 90 giorni
Sottosezione intitolata “Il console e API sovrascrivono scadono dopo 90 giorni”Forced mappings and Dashboard or Public API channel overrides are stored as per-device assignments in Capgo. A cleanup job deletes those assignments 90 giorni dopo l'ultima scrittura di overrideControllare l'aggiornamento non resettare quel timer. Solo la scrittura dell'override nuovamente (o cancellandolo da solo) cambia la data.
Questo non è lo stesso di la conservazione dell'inventario dei dispositivi. L'inventario elimina i dispositivi che non si sono collegati a Capgo per 90 giorni. La pulizia dell'override elimina la mappatura anche se il dispositivo è ancora attivo.
Per un'assegnazione che non viene eliminata da questa pulizia:
- Impostare
defaultChannelincapacitor.config.*(resiste alla reinstallazione; richiede un nuovo binario nativo per cambiare in seguito). - Chiamare
setChannel()context: Appflow Migration Step2setChannel()dal'applicazione. Dal plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 e in seguito, quella assegnazione è locale e non viene eliminata da questa pulizia. Reinstallando l'app, si cancella, quindi l'app deve chiamare
Canale Dispositivi tab e il dispositivo Override UI solo elenca console e assegnazioni Publice API. Non elencano ogni dispositivo sul canale, e non elencano dispositivi locali setChannel() Assegnazioni.

Comportamento del Canale Predefinito
Sottosezione intitolata “Comportamento del Canale Predefinito”Impostare un default cloud è facoltativo, ma serve spesso come percorso di default per i nuovi dispositivi. Senza uno, solo i dispositivi che corrispondono alle mappature forzate, alle sovrapposizioni o a una defaultChannel Capacitor configurazione riceveranno aggiornamenti. Quando scegli di segnalare i default, tieni presente queste pattern:
- Default unico (più comune) – Se un canale ha iOS, Android e Electron abilitati, diventa il default unico; ogni dispositivo senza sovrapposizioni si attaccherà qui.
- Impostazioni specifiche della 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, i dispositivi 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. Aprire il canale, poi
Gestisci in Impostazioni dell'app Manage in App settingsche ti porta a Informazioni sull'app. Il default non è più un toggle sulla pagina del canale. Quando scambi un default, i nuovi dispositivi rispettano le nuove impostazioni di routing immediatamente e i dispositivi esistenti seguono le regole di precedenza normali la prossima volta che si connettono.
Configurazione di un Canale
Sottosezione intitolata “Configurazione di un Canale”Durante l'onboarding 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 sincronizzare i canali con le 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 di una maggiore diffusioneStaging- per le prove finali in un ambiente simile a quello di produzioneProduction- per la versione dell'app che gli utenti finali ricevono dai negozi di app
Configurare il Canale nell'App
Sezione intitolata “Configurare il Canale nell'App”Dopo aver creato i canali, è necessario configurare l'app per ascoltare il canale appropriato. In questo esempio, useremo il Development canale.
Aprite il vostro capacitor.config.ts (o capacitor.config.json) file. Sotto la plugins sezione, impostate optionalmente il defaultChannel per le costruzioni di test (internale / QA). Per le costruzioni di produzione, preferisci ometterlo in modo che i dispositivi utilizzino il Cloud Default a meno che non sia stato 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. }, },};Prossimo, 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. Puoi configurarle dall'app web, dal CLI, o dal Public API.
- Canale predefinito: Opzionalmente segnala i canali o i canali specifici per piattaforma che i nuovi dispositivi si collegano. In console questo vive nelle informazioni sull'app ('Gestisci le impostazioni dell'app da pagina del canale). Vedi “Comportamento del canale predefinito” per scenari di routing.
- Filtro per piattaforma: Abilita o disabilita la consegna a
iOS,AndroidoElectrondispositivi per canale. - Disabilita l'autoabbassamento sotto nativo: Impedisce di inviare un aggiornamento quando la versione dell'app nativa del dispositivo è più recente della versione del bundle del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
- Consenti edizioni di sviluppo: Consentire aggiornamenti alle edizioni di sviluppo (utili per la prova). CLI:
--dev/--no-dev. - Consenti costruzioni di produzione: Consenti gli aggiornamenti alle costruzioni di produzione (magazzino) lascia questo attivo per i canali che servono utenti reali. CLI:
--prod/--no-prod. - Consenti dispositivi emulatori: Consenti gli aggiornamenti ai dispositivi emulatori/simulatore (utile per le prove). CLI:
--emulator/--no-emulator. - Consenti dispositivi fisici: Consenti gli aggiornamenti ai telefoni e alle tablet reali. Lascia questo attivo per i canali di produzione. CLI:
--device/--no-device. - Consenti l'assegnazione di dispositivi da parte dell'applicazione: L'applicazione può passare a questo canale in esecuzione utilizzando
setChannelSe disabilitato,setChannelfallirà per questo canale. CLI:--self-assign/--no-self-assign. - Pacchetto di aggiornamento: Scegli se i dispositivi scaricano un file zip completo, un delta dei file modificati o entrambi (
all,zip,delta,zip_from_builtin,delta_from_builtinvedi Pacchetto di aggiornamento per il menu a discesa della console e quando ogni modalità è utile.
Rulli progressivi
Sezione intitolata “Rulli progressivi”A un canale è possibile mantenere un bundle stabile mentre si espongono gradualmente un obiettivo di distribuzione separato a un gruppo di dispositivi adesivi. Puoi sospendere, riprendere, promuovere, tornare indietro e configurare una risposta di fallimento automatica senza cambiare il canale per tutti. Vedi Rollout progressivo per il modello di consegna, il flusso di lavoro del dashboard, API campi e CLI comandi.
Disabilita strategie di aggiornamento automatico
Sottosezione intitolata “Disabilita strategie di aggiornamento automatico”Usa questo per limitare quali tipi di aggiornamenti il canale consegnerà automaticamente. Opzioni:
- maggiore: Blocca un bundle di destinazione con una versione maggiore di quella del baseline nativo del dispositivo (
version_buildEsempio:1.2.3 -> 2.0.0è bloccato;1.2.3 -> 1.9.0è consentito. - minore: Blocca un bundle di destinazione con una versione maggiore o minore rispetto a
version_buildEsempio:1.2.3 -> 1.3.0is blocked;1.2.3 -> 1.2.4is allowed. - patch: Modalità più rigorosa. Blocca qualsiasi modifica al numero maggiore, minore o di patch. Sono consentite solo le modifiche ai suffissi mentre
MAJOR.MINOR.PATCHrimane identico. Esempi:1.0.0-beta.1 -> 1.0.0-beta.2is allowed;1.0.0+build.1 -> 1.0.0+build.2is allowed;1.0.0 -> 1.0.1is blocked. - metadata: Richiede una versione minima di aggiornamento dei metadati per ogni bundle. Configurare tramite CLI usando
--min-update-versiono--auto-min-update-versionseleziona una delle opzioni disponibili. - seleziona una delle opzioni disponibili. seleziona una delle opzioni disponibili. Se mancante, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non sarà impostato..
Queste strategie confrontano la versione del canale di destinazione con la versione di base nativa inviata come version_build, non la versione del bundle scaricata attualmente inviata come version_name.
Scopri i dettagli e gli esempi in Disable updates strategy a /docs/cli/commands/#disable-updates-strategy.
Esempio (CLI). Il canale deve già esistere (channel set non lo crea):
# 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-assign
# Production channel: store builds on real devices, no emulatorsnpx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulatorUtilizzando setChannel() dal tuo App
Sottosezione intitolata “Utilizzando setChannel() dal tuo App”La setChannel() metodo consente al tuo app di cambiare canale in modo programmatico durante l'esecuzione. Ciò è particolarmente utile per:
- menu di QA/debug dove gli tester possono cambiare tra canali
- Flussi di opt-in per il programma beta
- Implementazioni delle bandiere di feature
- Scenari di testing 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});Assegnazione di un Bundle a un Canale
Sottosezione intitolata “Assegnazione di un Bundle a un Canale”Per distribuire un aggiornamento in tempo reale, è necessario caricare un nuovo build del bundle JS e assegnarlo a un canale. Ciò può essere fatto in un passo con il Capgo CLI:
npx @capgo/cli@latest bundle upload --channel=DevelopmentQuesto 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.
Puoi anche assegnare le build ai canali dalla sezione “Bundle” del Capgo dashboard. Clicca sul menu icona accanto a una build e seleziona “Assegna al canale” per scegliere il canale per quella build.
Versionamento dei bundle e canali
Sottosezione intitolata “Versionamento dei bundle e canali”È importante notare che i bundle in Capgo sono globali per l'app, non specifici per canali individuali. Lo stesso bundle può essere assegnato a più canali.
Quando versioni i bundle, consigliamo di utilizzare la versioning semantico con il Capgo’s Tester Semver e gli identificatori di pre-uscita per le build specifiche del canale. Ad esempio, una versione beta potrebbe essere versionata come In CI, se la versione locale era già caricata, utilizza 1.2.3-beta.1.
(facoltativamente) npx @capgo/cli@latest bundle upload --auto-bump , o major, minor, patch/fix, metadata) in modo che il __CAPGO_KEEP_0__ aumenti dal bundle del canale collegato fino a trovare un nome libero. Con ai) so the CLI bumps from the channel’s linked bundle until a free name is found. With aiWorkers AI determina il livello dalla manifest locale rispetto al delta precedente (ricade su patch con nessuna versione precedente Capgo). Non puoi combinarlo con --bundle. Vedi Integrazione CI/CD contexto: Pagina/area: Capgo Builder / prodotto di costruzione nativa cloud. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave di messaggio `native_build_feature_ci_cd` (Feature di costruzione nativa Ci Cd). CLI reference.
riferimento __CAPGO_KEEP_0__
- Questa approccio ha diversi benefici:
1.2.3-beta.1Comunica chiaramente la relazione tra le costruzioni.1.2.3. - è ovviamente una versione pre-release di
- Consente di riutilizzare i numeri di versione across canali, riducendo la confusione.
1.2.3Abilita percorsi di rollback chiari. Se hai bisogno di tornare indietro da , sai1.2.2è la versione di rilascio stabile precedente.
Ecco un esempio di come potresti allineare le versioni del tuo 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.2ecc.Productioncanale:1.2.3,1.2.4ecc.
Usando semver con identificatori di rilascio pre-annunciati è un approccio consigliato, ma non è strettamente necessario. 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.
Ripristino di una Aggiornamento in Tempo Reale
Sottosezione intitolata “Ripristino di una Aggiornamento in Tempo Reale”Se hai distribuito un aggiornamento in tempo reale che introduce un bug o che deve essere annullato, puoi facilmente ripristinare una versione precedente. Dalla sezione “Canali” del pannello di controllo:
- Clicca il nome del canale che desideri ripristinare
- Cerca la build che desideri annullare e clicca l'icona della corona

- Conferma l'azione
La build selezionata diventerà immediatamente la build attiva per quel canale. Le app riceveranno la versione ripristinata la prossima volta che controllano per un aggiornamento.
Automazione delle Distribuzioni
Sottosezione intitolata “Automazione delle Distribuzioni”Per flussi di lavoro più avanzati, puoi automatizzare le tue distribuzioni di aggiornamenti in tempo reale come parte del tuo pipeline CI/CD. Integrando Capgo nel tuo processo di build, puoi caricare automaticamente nuovi bundle e assegnarli ai canali ogni volta che puochi certi rami o crei nuove release.
Esegui una visita ai Integrazione CI/CD docs to learn more about automating Capgo live updates.
Documenti per imparare di più su come automatizzare gli aggiornamenti live di __CAPGO_KEEP_0__.
Previsioni di PR con minori privilegiSottosezione intitolata “Previsioni di PR con minori privilegi” Usa un API key when CI needs one temporary channel per pull request but must not manage existing main/default channels. The key remains bound to the owning organization and selected app; it simply has no organization-wide role. Each non-public preview channel it creates receives its own automatic, channel-scoped lifecycle permission.
- API chiave quando il CI ha bisogno di una canale temporaneo per ogni richiesta di commit, ma non deve gestire i canali esistenti predefiniti. La chiave rimane legata all'organizzazione proprietaria e all'app selezionata; semplicemente non ha alcun ruolo a livello di organizzazione. Ogni canale di anteprima non pubblico che crea riceve le proprie autorizzazioni di ciclo di vita automatiche, scritte a livello di canale. Hai un amministratore dell'organizzazione che crea una chiave __CAPGO_KEEP_0__ sicura limitata all'app di anteprima e selezionaAnteprima dell'app . Vedi le chiavi API.
- Usa un canale unico, non pubblico, come
pr-123Non passare--default,--self-assign, opzioni di rilascio, o--delete-linked-bundle-on-upload. - Carica e promuovi il bundle PR con un comando, quindi elimina il canale e il bundle di proprietà quando il 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 bundle e lo promuove in un flusso. La pulizia è atomica e controllata dall'accesso: la chiave può eliminare solo un canale che ha creato e il suo bundle collegato e non condiviso. Non può cambiare, promuovere o eliminare un canale principale/di default, un canale di anteprima di un'altra chiave o un bundle 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 permessione di impostazioni dell'app. In GitHub Actions, esegui i lavori di anteprima che contengono segreti su pull_request, non pull_request_target, e limitarli ai PR con repository identico con github.event.pull_request.head.repo.full_name == github.repository.
Deployare su un Dispositivo
Sottosezione intitolata “Deployare su un Dispositivo”Ora che hai capito i canali, sei pronto a iniziare a distribuire aggiornamenti live su dispositivi reali. Il processo base è:
- Installare il Capgo SDK nel tuo app
- Configura l'app per ascoltare il tuo canale desiderato
- Carica un build e assegna il canale a quel build
- Lancia l'app e aspetta l'aggiornamento!
Per un walkthrough dettagliato, consulta il Deployare Aggiornamenti Live guide. Buona fortuna con gli aggiornamenti!
Utilizzo avanzato dei canali: Segmentazione degli utenti
Sezione intitolata “Utilizzo avanzato dei canali: segmentazione degli utenti”I canali possono essere utilizzati per più di una fase di sviluppo. Sono uno strumento potente per la segmentazione degli utenti, che consente di attivare funzionalità come:
- Bandiere di feature per diversi livelli di utenti
- Test A/B
- Rollout di feature graduale
- Programmi di testing beta
Scopri come implementare questi casi d'uso avanzati nella nostra guida: Come segmentare gli utenti per piano e canali per le bandiere di feature e i test A/B.
Continua da qui dai canali
Sezione intitolata “Continua da qui dai canali”Se stai utilizzando I canali per pianificare la routing del canale e il rilascio in fase di staging, connettilo con Canali contexto: nome del feature di rilascio Canali. Pagina/area: pagina di marketing delle soluzioni Capgo. Ruolo: breve etichetta UI o elemento di navigazione. Visto in: pagina soluzioni/white-label.astro. Chiave di messaggio `solutions_white_label_visual_cell2_value` (Valore della cella visiva del white label delle soluzioni). per i dettagli di implementazione in Canali, Canali contexto: nome del feature di rilascio Canali. Pagina/area: pagina di marketing delle soluzioni Capgo. Ruolo: breve etichetta UI o elemento di navigazione. Visto in: pagina soluzioni/white-label.astro. Chiave di messaggio `solutions_white_label_visual_cell2_value` (Valore della cella visiva del white label delle soluzioni). per i dettagli di implementazione in Canali, Soluzione di Test Beta per il flusso di lavoro del prodotto in Soluzione di Test Beta, Capgo Environment Best Practices: Staging with One Mobile App ID for the practical context in Capgo Environment Best Practices: Staging with One Mobile App ID.