Canali
Copia un avviso di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Un canale di aggiornamento in tempo reale punta a una specifica costruzione di 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 costruzione a cui punta quel canale in qualsiasi momento e puoi anche tornare a costruzioni 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 gli utenti QA che passano tra i 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 atterrino su un canale di anteprima automaticamente. Le costruzioni di produzione lasciano spesso questo impostato su null. - 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 canale, nessuna configurazione defaultChannel) si attaccano qui. Modificare per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai dei default specifici per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo atterra sul default 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 imposti un canale predefinito, gli utenti reali dovrebbero flusso in esso. Se non lo imposti, essere deliberato su come gli utenti si attaccano (di solito tramite
defaultChannelconfigurare in config o sovrascrivere per dispositivo). - Sono abilitati solo la configurazione
defaultChannelconfigurare in binari che spedite esplicitamente ai tester. Lasciare in bianco mantiene la logica di produzione centralizzata nel dashboard. - Usare
setChannel()usare con parsimonia in produzione—principalmente per QA o diagnostica mirata.
Se un canale è disabilitato per la piattaforma (iOS/Android/Electron toggle) 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.
Console e API sovrascritture scadono dopo 90 giorni
Sottosezione intitolata “Console e API sovrascritture scadono dopo 90 giorni”I mapping obbligatori e le sovrascritture del dashboard o del canale pubblico API sono memorizzati come assegnamenti per dispositivo in Capgo. Un lavoro di pulizia elimina quegli assegnamenti 90 giorni dopo l'ultima scrittura di overrideLa verifica di un aggiornamento non resettare quel clock. 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 sono stati 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:
- Imposta
defaultChannelincapacitor.config.*(resiste alla reinstallazione; richiede un nuovo binario nativo per cambiare in seguito). - Chiamare
setChannel()contexto: frammento di testo HTML da una stringa Capgo UI più lunga (chiave genitoriale `appflow_migration_step2`). Pagina/area: Appflow comparison / migrazione marketing copy. Ruolo: copia del sito web frase. Visualizzato in: pagina ionic-appflow.astro. Preservare i termini del prodotto/marca e dei sviluppatori esattamente. Chiave del messaggio `appflow_migration_step2` (Appflow Migration Step2).setChannel()dal'app. 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 di solito funge da 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 regole:
- Default unico (più comune) – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico default; ogni dispositivo senza sovrapposizioni si attaccherà qui.
- Predefiniti specifici 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, gli Android vanno al default Android, e le applicazioni Electron vanno al default Electron.
Ricordate che il predefinito cloud e defaultChannel entrambi occupano lo stesso livello di decisione. Se impostate un predefinito 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 volete che inizino su un canale non di produzione anche se il predefinito cloud è diverso. defaultChannel Potete modificare i predefiniti in qualsiasi momento nel pannello di controllo. Aprire il canale, poi
Gestisci in Impostazioni dell'app Manage in App settingsquale 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 test finali in un ambiente simile a quello di produzioneProduction- per la versione dell'app che gli utenti finali ricevono dai negozi di app
Configurazione del canale nell'app
Sezione intitolata “Configurazione del canale nell'app”Dopo aver creato i canali, è necessario 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, impostare optionalmente defaultChannel per le versioni di test (interno / QA). Per le costruzioni 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. }, },};Costruisci successivamente la tua 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 configurati precedentemente.
Il canale Opzioni e strategie
Sezione intitolata “Opzioni e strategie del canale”Il canale hanno diverse opzioni che controllano chi può ricevere aggiornamenti e come gli aggiornamenti sono consegnati. Le più importanti sono quelle elencate di seguito. Puoi configurare queste dalla app web, il CLI, o il Public API.
- Canale predefinito: Opzionalmente segnala il canale o i canali specifici per piattaforma che i nuovi dispositivi si collegano. In questo caso vive nella console App Information (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,Androido dispositivi per canale.ElectronDisabilita l'auto downgrade 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 costruzioni di sviluppo: Consentire gli aggiornamenti alle costruzioni di sviluppo (utili per la prova). __CAPGO_KEEP_0__:
- Allow development builds: Permit updates to development builds (useful for testing). CLI:
--dev/--no-dev. - Consenti costruzioni di produzione: Consentire aggiornamenti alle costruzioni di produzione (archivio) lasciare questo attivo per i canali che servono utenti reali. CLI:
--prod/--no-prod. - Consenti dispositivi emulatori: Consentire aggiornamenti ai dispositivi emulatori/simulatore (utile per le prove). CLI:
--emulator/--no-emulator. - Consenti dispositivi fisici: Consentire aggiornamenti a telefoni e tablet reali. Lasciare 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: Scegliere se i dispositivi scaricano un file zip completo, una delta dei file modificati o entrambi (
all,zip,delta,zip_from_builtin,delta_from_builtinvedere 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 pacchetto stabile mentre si espongono gradualmente un obiettivo di distribuzione separato a un gruppo di dispositivi fedeli. Vedi for the delivery model, dashboard workflow, API fields, and CLI commands.
per il modello di consegna, il flusso di lavoro del pannello di controllo, __CAPGO_KEEP_0__ campi e __CAPGO_KEEP_1__ comandi.
Disabilita strategie di aggiornamento automaticoSottosezione intitolata “Disabilita strategie di aggiornamento automatico”
- Utilizza questo per limitare i tipi di aggiornamenti che il canale consegnerà automaticamente. Opzioni:
version_buildmaggiore: Blocca un pacchetto di destinazione con una versione maggiore rispetto alla versione nativa del dispositivo di base (1.2.3 -> 2.0.0esempio:1.2.3 -> 1.9.0è bloccato; - è consentito.
version_buildminore: Blocca un pacchetto di destinazione con una versione maggiore o minore rispetto a quella di base (esempio:1.2.3 -> 1.3.0is blocked;1.2.3 -> 1.2.4is allowed. - patch: Modalità più rigorosa. Blocca qualsiasi modifica al numero di versione 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: Richiedi una versione di aggiornamento minima nel metadati di ogni bundle. Configura tramite CLI usando
--min-update-versiono--auto-min-update-versionSe manca, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non viene impostato. - nessuna: Consentire tutti gli aggiornamenti secondo la compatibilità di semver o.
E queste strategie confrontano la versione del canale di destinazione con la versione di base nativa inviata come version_build, non la versione del canale scaricata attualmente inviata come version_name.
Scopri di più dettagli e esempi nella strategia di disabilitazione degli aggiornamenti in /docs/cli/comandi/#disabilita-aggiornamenti.
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 passare dinamicamente tra i canali durante l'esecuzione. Ciò è particolarmente utile per:
- menu di debug/QA dove i tester possono passare tra i 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 live, è necessario caricare un nuovo build del bundle JS e assegnarlo a un canale. Ciò può essere fatto in un'unica operazione 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. Tutti gli app configurate per ascoltare quel canale riceveranno l'aggiornamento la prossima volta che ne cercheranno uno.
Puoi anche assegnare le build ai canali dalla sezione “Pacchetti” del Capgo dashboard. Clicca sull'icona del menu accanto a una build e seleziona “Assegna a canale” per scegliere il canale per quella build.
Pacchettazione e canali
Sezione intitolata “Pacchettazione e canali”È importante notare che i pacchetti in Capgo sono globali per la tua app, non specifici per canali individuali. Lo stesso pacchetto può essere assegnato a più canali.
Quando versioni i pacchetti, consigliamo di utilizzare la versioning semantico con il Capgo Semver Tester e gli identificatori di pre-uscita per le build specifiche del canale. Ad esempio, una versione beta potrebbe essere versionata come 1.2.3-beta.1.
In CI, se la versione locale era già caricata, utilizza npx @capgo/cli@latest bundle upload --auto-bump (facoltativamente) major, minor, patch/fix, metadata, o ai) in modo che il CLI aumenti dal pacchetto collegato del canale fino a trovare un nome libero. Con ai, Workers 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 build 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.
Utilizzando semver con identificatori di rilascio pre-annunciati è 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.
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” della dashboard:
- Clicca sul nome del canale che desideri ripristinare
- Cerca la build che desideri ripristinare e clicca sull'icona della corona

- Conferma l'azione
La build selezionata diventerà immediatamente la build attiva per quel canale. Gli 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 certe branch 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ù sulle automatizzazioni delle __CAPGO_KEEP_0__ aggiornamenti in tempo reale.
Previsioni PR con privilegi minimiSottosezione intitolata “Previsioni PR con privilegi minimi” 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 pull, 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ò modificare, 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 possibilità di modificare le impostazioni dell'app. In GitHub Actions, esegui i lavori di anteprima che contengono segreti su pull_requestnon 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 attendi l'aggiornamento!
Per un walkthrough dettagliato, vedi 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
- Rilascio graduale di feature
- Programmi di test 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 la distribuzione in fase di staging, connettilo con 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 di produzione: Staging con un ID di App Mobile per il contesto pratico in Capgo Pratiche per l'ambiente di produzione: Staging con un ID di App Mobile