Canali

Copia un prompt 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 versione costruita 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 quel canale in qualsiasi momento e puoi anche tornare a versioni precedenti se necessario.

Come un dispositivo sceglie un canale (precedenza)

Quando un dispositivo controlla l'aggiornamento, Capgo decide quale canale utilizzare in questo ordine rigoroso (priorità più alta per prima):

Mapping dispositivo protetto (Dashboard) – Pianifica manualmente un ID dispositivo specifico a un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo sempre vince.
Cloud override (per dispositivo) via Dashboard o API – Creato quando cambia il canale del dispositivo nella 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'entry dispositivo si cancella.
Plugin setChannel() canale locale – Creato quando l'app chiama setChannel() e il backend verifica che il canale di destinazione consente l'assegnazione auto. Il canale selezionato viene memorizzato localmente su quel dispositivo, ha effetto immediato e non viene visualizzato nell'interfaccia di sovrascrittura del dispositivo.

Da plugin versione 5.34.0, 6.34.0, 7.34.0 o 8.0.0 (in base alla tua versione maggiore), setChannel() funziona in modo diverso: contatta il backend per validare che il canale sia consentito (verificando se l'assegnazione auto è abilitata per quel canale), quindi memorizza il canale localmente sul dispositivo come defaultChannel. Ciò significa che il nuovo canale ha effetto istantaneamente per la prossima verifica degli aggiornamenti—nessuna attesa per la riproduzione dei dati.

In precedenza, setChannel() salvava l'override del canale nel database backend (come Dashboard o API modifiche), e i dispositivi dovevano attendere la riproduzione dei dati (fino a 2 minuti) prima che il nuovo canale fosse riconosciuto. Il nuovo comportamento legge solo dal backend (per la validazione) e memorizza localmente, rendendo le scelte dei canali istantanee.

Poiché è locale, non crea un'ingresso di override dispositivo nel __CAPGO_KEEP_0__ dashboard. setChannel() La UI dell'override dispositivo mostra solo gli override creati dal dashboard o dal Public __CAPGO_KEEP_1__. Nota: create a Device Override entry in the Capgo dashboard. The Device Override UI only shows overrides created from the dashboard or the Public API.

Importante: Quando si fanno modifiche ai canali tramite il Dashboard o __CAPGO_KEEP_0__, c'è ancora un ritardo di replicazione di fino a 2 minuti prima che tutti i server di edge riflettano il cambiamento. Per un cambio di canale istantaneo, utilizza

dal tuo app __CAPGO_KEEP_0__—valida con il backend, quindi imposta il canale localmente per effetto immediato. Configurazione API setChannel() from your app code—it validates with the backend, then sets the channel locally for immediate effect.

Capacitor config defaultChannel __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ capacitor.config.* And se non esiste alcun canale forzato/override/locale, l'app inizia su questo canale (ad esempio, beta, qa, pr-123Inteso per TestFlight/costruzioni interne, in modo che i tester cadano su un canale pre-rilascio automaticamente. Le costruzioni di produzione lasciano spesso questo impostato.
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 canale locale del plugin, nessuna configurazione predefinita del canale) si connettono qui. Cambialo per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai impostazioni predefinite specifiche per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo si connette al 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:

Tratta 1-4 come livelli di eccezione/test; quando imposti un canale predefinito, gli utenti reali dovrebbero flusso in esso. Se non scegli di impostarlo, sii deliberato su come gli utenti si connettono (tipicamente via defaultChannel in configurazione o sovrascritture per dispositivo).
Configura solo defaultChannel in binari che spedisci esplicitamente ai tester. Lasciarlo non impostato mantiene la logica di produzione centralizzata nel pannello di controllo.
Usa setChannel() 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 a scendere la lista.

Riepilogo: Forza > Dashboard/API Override > Plugin setChannel() canale locale > Config defaultChannel > Cloud Default.

Comportamento del canale predefinito

Impostare un cloud predefinito è facoltativo, ma serve spesso come percorso di default per i nuovi dispositivi. Senza uno, solo i dispositivi che corrispondono alle mappature forzate, agli override o a defaultChannel nel config Capacitor riceveranno aggiornamenti. Quando scegli di segnalare i valori predefiniti, tieni presente:

Default unico (più comune) – Se un canale ha abilitato iOS, Android e Electron, diventa l'unico default; qualsiasi dispositivo senza override si attaccherà qui.
Default specifici per piattaforma – Se si suddivide i canali per piattaforma (ad esempio, ios-production con solo iOS abilitato, android-production With solo Android abilitato, e electron-production Con solo Electron abilitato, segnala ciascuno come predefinito per la propria piattaforma. I dispositivi iOS vanno al default iOS, i dispositivi Android vanno al default Android e le applicazioni Electron vanno al default Electron.

Ricorda che il cloud default e defaultChannel entrambi occupano lo stesso livello di decisione. Se imposti un cloud default, non hai bisogno di duplicare il valore nella tua __CAPGO_KEEP_0__ configurazione— lascia 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 intendi spedire ai tester o QA quando vuoi che inizino su un canale non di produzione anche se il cloud default è diverso. defaultChannel Puoi modificare i default in qualsiasi momento nel pannello di controllo. 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”

Vai alla sezione “Canali” del pannello di controllo __CAPGO_KEEP_0__

Go to the “Channels” section of the 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 è quella di associare i canali alle tue fasi di sviluppo, ad esempio:

Development - per testare aggiornamenti in tempo reale su dispositivi locali o emulatori
QA - per il tuo team di QA per verificare gli aggiornamenti prima della loro pubblicazione più ampia
Staging - per il testing finale in un ambiente simile a quello di produzione
Production - per la versione del tuo app che gli utenti finali ricevono dai negozi di app

Configurazione del Canale nell'App

Dopo aver creato i canali, devi configurare l'app per ascoltare il canale appropriato. In questo esempio, useremo il Development canale.

Apri il capacitor.config.ts Attenzione capacitor.config.jsonSotto la sezione, è possibile impostare plugins per defaultChannel costruzioni di test (interni / QA). Per le costruzioni di produzione, preferisci ometterlo in modo che i dispositivi utilizzino il Cloud Default a meno che non venga esplicitamente sovrascritto. Copia negli appunti

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.
    },
  },
};

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. npx cap sync Attenzione

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 le impostazioni specifiche del canale che i nuovi dispositivi si collegano a. Vedi “Comportamento del canale predefinito” per gli scenari di routing.
Filtro delle piattaforme: Attiva o disattiva la consegna a iOS, Android, o Electron dispositivi per canale.
Disabilita l'autoabbassamento sotto nativo: Impedisce di inviare un aggiornamento quando la versione dell'applicazione nativa del dispositivo è più recente della versione del pacchetto del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
Consenti aggiornamenti di build di sviluppo: Consentire aggiornamenti ai build di sviluppo (utile per la prova).
Consenti dispositivi emulatori: Consentire aggiornamenti ai dispositivi emulatori/simulatori (utile per la prova).
Consenti l'assegnazione di dispositivo a sé: Consente all'app di passare a questo canale in esecuzione utilizzando setChannel. Se disabilitato, setChannel fallirà per questo canale.

Rollout progressivi

Un canale può mantenere un pacchetto stabile mentre esporre gradualmente un obiettivo di rollout 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 progressivi per il modello di consegna, il flusso di lavoro del dashboard, API campi e CLI comandi.

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 la cui versione maggiore è superiore alla versione di base nativa del dispositivo (version_build). Esempio: 1.2.3 -> 2.0.0 è bloccato; 1.2.3 -> 1.9.0 è consentito.
minore: Blocca un pacchetto di destinazione la cui versione maggiore o minore differisce da version_build. Esempio: 1.2.3 -> 1.3.0 è bloccato; 1.2.3 -> 1.2.4 è consentito.
patch: Modalità più rigorosa. Blocca qualsiasi cambiamento al numero di versione maggiore, minore o patch. Sono consentiti solo cambiamenti di suffisso mentre MAJOR.MINOR.PATCH stays 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: Richiedi una versione di aggiornamento minima metadata su ogni bundle. Configura tramite CLI utilizzando --min-update-version o --auto-min-update-version. Se mancante, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non viene impostato.
nessuno: Consentire tutti gli aggiornamenti in base alla compatibilità di semver Queste strategie confrontano il bundle di destinazione del canale contro la base nativa inviata come.

e non il bundle scaricato correntemente inviato come version_buildScopri i dettagli e gli esempi in Disable updates strategy alla sezione /docs/__CAPGO_KEEP_0__/commands/#disable-updates-strategy. version_name.

Learn more details and examples in Disable updates strategy at /docs/cli/commands/#disable-updates-strategy.

Esempio (CLI):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

Utilizzo di setChannel() dal tuo App

Il setChannel() metodo consente al tuo app di cambiare canali in modo programmatico durante l'esecuzione. Questo è particolarmente utile per:

Menu di QA/debug dove gli tester possono cambiare tra canali
Flussi di opzione per il programma beta
Implementazioni delle bandiere di feature
Scenari di test A/B

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });

// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

When setChannel() è chiamato:

Scheda di validazione backend (lettura sola): Viene inviata una richiesta al backend Capgo per validare che il canale sia consentito (verificando le autorizzazioni di assegnazione auto)
Aggiornamento del storage locale: Se la validazione ha successo, il canale viene salvato nel storage locale del dispositivo come defaultChannel
Effetto immediato: La prossima verifica di aggiornamento utilizza il nuovo canale immediatamente (nessuna attesa per la replica)

Perché conta: In versioni precedenti, setChannel() ha salvato l'override del canale sul database backend (lo stesso di Dashboard o API modifiche). Gli dispositivi dovevano attendere la replica del backend (fino a 2 minuti) prima che l'override del canale avesse effetto. Ora, setChannel() legge solo dal backend (per la validazione) e memorizza localmente, rendendo le transizioni tra canali istantanee.

Visibilità del Dashboard: Un canale impostato con il plugin non fa apparire il dispositivo come un Override del dispositivo nella Capgo UI. Solo le assegnazioni di canale create dal dashboard o dal Public API sono elencate lì. Utilizza il dashboard o API quando hai bisogno di un override visibile dagli amministratori.

Nota di sicurezza: Anche se i permessi di un canale cambiano dopo essere stati impostati localmente (ad esempio, l'auto-assegnazione è disabilitata), il backend valuterà ancora il canale durante le verifiche di aggiornamento, garantendo la sicurezza.

Confronto dei metodi di modifica del canale:

Metodo	Effetto Tempo	Persistente in	Mostrato nell'UI Override del dispositivo	Utilizzo del caso
`setChannel()` da plugin	Istantaneo	Solo dispositivo (locale)	No	Spostamento del canale inizializzato dall'utente all'interno dell'app
Superamento del canale dispositivo del dashboard	Fino a 2 min	Database del backend	Sì	Modifiche iniziate dall'amministratore per dispositivi specifici
API assegnazione del canale	Fino a 2 min	Database del backend	Sì	Integrazioni backend automatizzate

Per garantire l'esperienza utente migliore quando si sviluppano UI di cambio canale, utilizzare sempre il metodo del plugin. setChannel() metodo.

Versioni minime per il cambio canale locale solo: 5.34.0, 6.34.0, 7.34.0, o 8.0.0 (in base alla tua versione principale). Ogni numero di versione minore corrisponde allo stesso set di funzionalità in tutte le versioni principali (ad esempio, X.34.0 include le stesse funzionalità indipendentemente dal fatto che X sia 5, 6, 7 o 8). Vedi installazione del plugin per le etichette di versione.

Assegnare un Bundle a un Canale

To per distribuire un aggiornamento live, è necessario caricare un nuovo bundle di build JS e assegnarlo a un canale. Puoi farlo in un solo passo con il Capgo CLI:

npx @capgo/cli@latest bundle upload --channel=Development

Questo caricherà i tuoi asset web costruiti e stabilirà il nuovo bundle come build attiva per il Development canale. Qualsiasi app configurata per ascoltare quel canale riceverà l'aggiornamento la prossima volta che controlla per uno.

È anche possibile assegnare le costruzioni ai canali dalla sezione “Bundle” del Capgo dashboard. Clicca sul menu icona accanto a una costruzione e seleziona “Assegna al canale” per scegliere il canale per quella costruzione.

Versionamento dei bundle e dei canali

È importante notare che i bundle in Capgo sono globali per la tua app, non specifici per canali individuali. Lo stesso bundle può essere assegnato a più canali.

Quando versioni i tuoi bundle, consigliamo di utilizzare la versioning semantico con il Capgo’s Tester Semver e gli identificatori di pre-uscita per le costruzioni specifiche dei canali. Ad esempio, una versione beta potrebbe essere versionata come 1.2.3-beta.1.

Questa approccio ha diversi benefici:

Chiaramente comunica la relazione tra le costruzioni. 1.2.3-beta.1 è ovviamente una versione pre-rilascio di 1.2.3.
Consente di riutilizzare i numeri di versione in più canali, riducendo la confusione.
Consente percorsi di rollback chiari. Se hai bisogno di tornare indietro da 1.2.3, you know 1.2.2 , sai

è la versione stabile precedente.

Development Ecco un esempio di come potresti allineare le versioni dei pacchetti con un setup di canale tipico: 1.2.3-dev.1, 1.2.3-dev.2canale:
QA , ecc. 1.2.3-qa.1, 1.2.3-qa.2canale:
Staging canale: 1.2.3-rc.1, 1.2.3-rc.2, ecc.
Production canale: 1.2.3, 1.2.4, ecc.

Utilizzo l'uso di semver con identificatori di versione pre-rilascio è un approccio consigliato, 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 in un Aggiornamento in Tempo Reale

Se si distribuisce un aggiornamento in tempo reale che introduce un bug o che altrimenti necessita di essere annullato, si può facilmente tornare indietro a una versione precedente. Dalla sezione “Canali” del pannello di controllo:

Cliccare sul nome del canale da cui si desidera tornare indietro
Cercare la versione da cui si desidera tornare indietro e cliccare sull'icona della corona
Conferma l'azione

La costruzione selezionata diventerà immediatamente la costruzione attiva per quel canale. Gli app riceveranno la versione ripristinata la prossima volta che controllano per eventuali aggiornamenti.

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 bundle e assegnarli ai canali ogni volta che puoi spingere su determinate branch o creare nuove rilasci.

Esegui la consultazione dei Integrazione CI/CD documenti per imparare di più sull'automazione degli aggiornamenti live di Capgo.

Previsualizzazioni PR con privilegi minimi

Usa un Anteprima dell'app API chiave quando il CI ha bisogno di un 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; semplicemente non ha alcun ruolo a livello organizzativo. Ogni canale di anteprima non pubblico che crea riceve le proprie autorizzazioni di ciclo di vita automatiche e scoperte al canale.

Creare un amministratore di organizzazione una chiave API sicura limitata all'app di anteprima e selezionare Anteprima dell'app. Vedi Chiavi API.
Usare un canale unico e non pubblico come pr-123. Non passare --default, --self-assign, opzioni di rilascio o --delete-linked-bundle-on-upload.
Carica e promuovi il bundle della PR in un comando, poi cancella il canale di proprietà e il bundle 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-found

bundle upload --channel crea un canale mancante, carica il bundle e lo promuove in un flusso unico. La pulizia è atomica e controllata da proprietà: la chiave può cancellare solo un canale che ha creato e il suo bundle collegato, non condiviso. Non può cambiare, promuovere o cancellare un canale principale/predefinito esistente, un canale di un'altra chiave di anteprima 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" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

Una 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 limitali a PRs con repository stesso con github.event.pull_request.head.repo.full_name == github.repository.

Deploying to a Device

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 quello
Lancia l'app e attendi l'aggiornamento!

Per una guida dettagliata, vedi il Deploying Live Updates aggiornamento in tempo reale

guida. Buon aggiornamento!

Sottosezione 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:
Flag di funzionalità per diversi livelli di utenti
Test A/B
Rollout graduale delle funzionalità

Scopri come implementare questi casi d'uso avanzati nella nostra guida: Come segmentare gli utenti per piano e canali per le bandiere dei feature e il testing A/B.

Continua da Canali

Se stai utilizzando Canali per pianificare la routing dei canali e il rollout in fase di staging, connettilo con Canali per i dettagli di implementazione in Canali, Canali per i dettagli di implementazione in Canali, Soluzione di Testing Beta per il workflow del prodotto nella Soluzione di Test Beta, Soluzione di Targetizzazione della Versione per il workflow del prodotto nella Soluzione di Targetizzazione 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.