Canali

Nuovo con i canali? Guarda tre brevi video sui canali per vedere routing predefinito, self-assignment del dispositivo e override della console.

Il @capgo/capacitor-updater metodi setChannel() e unsetChannel() in questa guida sono supportati solo su Android e iOS. Non cambiano il routing del canale nelle anteprime browser.

Come Capgo sceglie un canale (precedenza)

Quando un dispositivo richiede un aggiornamento a Capgo, il canale utilizzato viene deciso in questo ordine (priorità massima per primo):

1. Mapping forzato del dispositivo: Se il device ID è forzato esplicitamente su un canale (il Dispositivi tab nella pagina del canale), quel canale ha sempre la precedenza. Le mappature forzate sono override della console/API. Capgo le rimuove 90 giorni dopo l'ultima scrittura dell'override. Vedi Gli override di console e API scadono.
2. Override cloud (Dashboard o API pubblica): Cambiare il canale di un dispositivo nella dashboard o tramite la API pubblica crea un override legato a quell'ID dispositivo. Reinstallare l'app non lo hai cancella; eliminare l'override sì. Vale lo stesso periodo di conservazione di 90 giorni.
3. Plugin setChannel() (locale): Sulle versioni attuali del plugin, setChannel() salva il canale sul dispositivo dopo la validazione del backend. Non è un override della dashboard. Su Android e iOS con updater 8.51.0 e successivi, persistDefaultChannelOnReinstall ha come default true, quindi la scelta persiste dopo la reinstallazione solo se il sistema operativo ripristina i dati dell'app e persistDefaultChannelOnReinstall rimane true. Chiama unsetChannel() per cancellare esplicitamente la scelta locale.
4. Configurazione Capacitor defaultChannel (default build di test): Per build interne / beta / di test puoi impostare defaultChannel (chiave legacy channel) in capacitor.config.* così i dispositivi di test partono su un canale pre-release (es. beta, pr-123). Se assente, il dispositivo userà il default cloud. Le build di produzione solitamente non hanno questo valore.
5. Cloud Default Channel (strategia principale per il ~99% degli utenti): Il canale di produzione principale su cui approdano quasi tutti gli utenti reali. Qualsiasi nuovo dispositivo senza un force, senza un override o senza un locale setChannel(), e senza una config defaultChannel usa questo. Cambiandolo, il rollout (o rollback) avviene per tutti in pochi secondi, senza nuovi binari.

Perché il cloud predefinito è il percorso principale:

• Rollout o rollback istantaneo senza dover ricostruire o ripubblicare i binari nativi.
• Un unico posto per gestire il comportamento di iOS, Android ed Electron.
• Più sicuro: puoi verificare l'esistenza dei bundle e la correttezza delle impostazioni prima di cambiare il default.
• Modifiche tracciabili (i membri del team possono vedere chi ha modificato cosa nell'UI / nei log).\nPrincipio di design: gli strati superiori (force / override / config) sono eccezioni (debug per singolo utente, switch QA, test dei default di build). Gli utenti normali passano al default cloud.

Cambiando il cloud predefinito il canale influisce nuovo dispositivi normali che:

• Non sono forzati
• Non hanno già un override cloud
• Non hanno un override a livello app defaultChannel definito

Se una build di test viene rilasciata con defaultChannel: 'beta' e in seguito cambi il cloud predefinito in production, i dispositivi avviati su beta tramite la configurazione, finché non viene applicata un'assegnazione a priorità più alta o finché non pubblichi un binario senza defaultChannel. Eliminare un force, un override cloud o un' setChannel() assegnazione locale non rimuove il valore della config; il fallback resta fino al nuovo binary.

I dispositivi restano sul canale attuale a meno che tu non:

• Li forzi su un altro canale (console o Public API).
• Modifichi l'override cloud nella dashboard o in Public API.
• Chiama setChannel() (assegnazione locale sulle versioni attuali del plugin).
• Rimuova / archivi il canale su cui si trovano (al prossimo check torneranno a seguire la precedenza).
• Attenda che un override console/API scada dopo 90 giorni.
• Chiama unsetChannel() per eliminare un' setChannel() assegnazione locale. Questo non rimuove un override console/API o un'assegnazione configurata dall'app. defaultChannel; si applica nuovamente la precedenza normale.
• Reinstalla l'app, operazione che può cancellare un'assegnazione locale su versioni precedenti dell'updater o quando i dati dell'app non vengono ripristinati. Su Android e iOS con updater 8.51.0 e successivi, persistDefaultChannelOnReinstall ha come default true, quindi i dati dell'app ripristinati possono preservare la scelta locale solo finché questa opzione rimane true. Gli override di Console/API non ne risentono.

Se un canale è disabilitato per una piattaforma (vedi i toggle iOS / Android / Electron) e altrimenti sarebbe stato selezionato, la selezione lo salta e passa alla regola successiva.

Nota: Impostare defaultChannel significa che per cambiarlo serve un nuovo binario; usalo intenzionalmente per test/QA, non per il controllo generale in produzione.

Esempio di configurazione Capacitor

capacitor.config.ts

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

Se in seguito modifichi il default del dashboard a production, i dispositivi già su un altro canale (tramite config, override o force) NON si sposteranno automaticamente; solo i nuovi dispositivi (o quelli il cui override/force viene rimosso) lo riceveranno.

---

Gestione dei canali

Per prima cosa, diamo un'occhiata alla pagina dei canali. Puoi accedervi cliccando sulla tua app e poi cliccando sulla tab channels.

Creare un canale

Come puoi vedere, c'è un pulsante plus in basso a destra. (1 (nell'immagine) Cliccandoci sopra si aprirà una modal per creare un nuovo canale.

Poi, dopo aver cliccato su Add un nuovo canale dovrebbe apparire nella lista.

Cosa significa “misconfigured”?

A volte la configurazione di un canale non è valida. In tal caso, apparirà un avviso e la Misconfigured colonna indicherà Yes per uno o più canali. Puoi approfondire qui qui

Eliminare un canale

Per eliminare un canale dalla web app, apri la Canali tab della tua app e individua la riga del canale. Nella Azione colonna, clicca sull'icona del cestino, quindi clicca Elimina nella finestra di conferma.

Se l'icona del cestino non è visibile, il tuo account non ha i channel.delete permessi per quell'app. Chiedi a un admin dell'organizzazione o dell'app di assegnarti un ruolo con permessi di eliminazione, oppure elimina il canale usando una API key autorizzata:

npx @capgo/cli@latest channel delete <channel-name> <app-id>

Una chiave legata all'organizzazione e all'app Anteprima App può eliminare in modo atomico solo il canale di anteprima non pubblico e il bundle creato con channel delete <preview-channel> <app-id> --delete-bundleNon può modificare o eliminare un canale principale/predefinito esistente, il canale di un'altra preview key o il bundle di un'altra key. Vedi Chiavi API per la configurazione con privilegi minimi.

Gestire un canale

Clicca sul nome del canale per aprire la relativa pagina. Si tratta di una pagina completa con tab, non di un modal.

Tab del canale

• Dashboard: Statistiche di installazione e di adozione del bundle corrente per questo canale.
• Informazioni: Impostazioni del canale elencate sotto, oltre al rollout progressivo e al Test Update API.
• Dispositivi: Mappature forzate create solo dalla console o dal API pubblico. Non elenca ogni dispositivo attualmente sul canale, né i dispositivi che hanno usato setChannel(). Consulta Gli override di console e API scadono.
• Cronologia: Modifiche alle impostazioni e ai bundle per questo canale.
• Anteprima: Anteprima nel browser e nativa del bundle collegato. Abilita l'anteprima del bundle in Informazioni sull'app prima.

Impostazioni informazioni

Rimani nella scheda Informazioni . Le impostazioni appaiono in questo ordine:

First, Canale di download predefinito è un badge di stato, non un toggle. Attivo significa che questo canale è il default cloud per i nuovi dispositivi. Clicca su Gestisci nelle impostazioni dell'app per cambiare il default su Informazioni sull'app. Per i default specifici per piattaforma (uno per iOS, uno per Android e uno per Electron), consulta la stessa sezione.

Secondo il IOS impostazione. Se impostata su false, i dispositivi iOS non potranno scaricare gli aggiornamenti da questo canale.

In terzo luogo, l'impostazione Android impostazione. Se impostata su false, i dispositivi Android non potranno scaricare gli aggiornamenti da questo canale.

In quarto luogo, l'impostazione Electron impostazione. Se impostata su false, le app Electron non potranno scaricare aggiornamenti da questo channel.

In quinto luogo, l'impostazione Disable auto downgrade under native impostazione. Se è attiva, non sarà possibile eseguire il downgrade da una versione nativa. Ciò significa che se hai caricato una 1.2.0 versione sull'App Store o sul Play Store e provi a impostare la versione del canale su 1.1.0 l'aggiornamento (downgrade) fallirà.

La sesta è l'impostazione Disable auto update. Questa impostazione è piuttosto complessa e puoi saperne di più qui

La settima è Download format l'impostazione. Determina se i dispositivi devono scaricare un file zip completo, solo i file delta modificati o il meglio di entrambi. Vedi Formato download.

L'ottava è Allow development build. Se è attiva, le development build potranno scaricare gli aggiornamenti da questo canale. Altrimenti, qualsiasi richiesta di aggiornamento che abbia un valore prod impostato su false verrà rifiutata. È utile soprattutto per i test.

Il nono è Allow production build. Se è false, le build di produzione (store) non riceveranno aggiornamenti da questo canale. Mantienilo attivo per i canali destinati agli utenti reali.

Il decimo è Allow Emulators. Se questo valore è false, Capgo bloccherà qualsiasi richiesta di update proveniente da un emulatore. Questa opzione è utile principalmente per scopi di testing.

L'undicesimo è Allow physical devices. Se è false, Capgo rifiuterà le richieste di aggiornamento da smartphone e tablet reali. Mantienilo attivo per i canali di produzione.

Il dodicesimo è Allow devices to self dissociate/associate. Se questo è vero, allora il metodo setChannel il metodo sarà disponibile su Android e iOS. Se questo valore è impostato su false e provi a chiamare metodo setChannel con questo canale, la chiamata fallirà.

Test Update API

At the bottom of the Informazioni scheda, espandi Test Update API. Capgo mostra un comando curl verso /updates per un dispositivo di esempio su questo channel.

A causa della cache, le modifiche possono impiegare fino a 60 secondi per apparire nel API. Se il channel non può essere testato, la console ti avvisa: il channel richiede almeno una piattaforma (iOS o Android), build di produzione, dispositivi fisici e deve essere il channel di download predefinito oppure consentire l'auto-assegnazione del dispositivo.

Invia notifica di aggiornamento

Dopo aver modificato il bundle collegato, la console può chiederti di Invia notifica di aggiornamento. Questo accoda un push silenzioso così i dispositivi sul canale controllano subito se c'è un nuovo bundle. Configura prima le credenziali push Android e iOS nella scheda Notifications dell'app.

Gli override di console e API scadono

Vengono rimosse le mappature forzate e le override dei canali API Dashboard/Public 90 giorni dopo l'ultima scrittura di override. L'ultimo check-in del dispositivo non azzera quel timer. Per un'assegnazione che sopravvive a quella pulizia, imposta defaultChannel nella tua configurazione Capacitor (sopravvive alla reinstallazione, serve un nuovo binario per modificarla) o chiama setChannel() da un'app Android o iOS usando @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, o 8.0.0+ per la versione major del tuo plugin. Queste versioni salvano l'assegnazione localmente, così si evita la pulizia dei 90 giorni. Le versioni precedenti scrivono un override sul backend soggetto alla stessa pulizia. Su Android e iOS con updater 8.51.0 e versioni successive, persistDefaultChannelOnReinstall ha come default true, quindi una selezione locale può sopravvivere a una reinstallazione solo se il sistema operativo ripristina i dati dell'app e persistDefaultChannelOnReinstall rimane true. Una reinstallazione con persistDefaultChannelOnReinstall: false può cancellare quella selezione locale anche se i dati dell'app vengono ripristinati. Usa unsetChannel() per cancellare esplicitamente quella selezione locale.

Sovrascrivi la retention nella scheda Devices del canale. Lo stesso avviso appare quando forzi un device ID sul canale.

Questo è separato da ritenzione dell'inventario dei dispositivi. L'inventory rimuove i device che non si sono connessi a Capgo da 90 giorni. L'override della cleanup rimuove il mapping anche se il device è ancora attivo. Dettagli completi: Gli override di Console e API scadono dopo 90 giorni.

Formato download

Apri un canale e rimani sulla Informazioni scheda. Formato download è nell'elenco delle impostazioni, sotto Disable auto update.

Download format nella scheda Information del canale. I nuovi canali usano Zip + delta per impostazione predefinita.

Questa impostazione determina cosa invia Capgo quando un dispositivo su questo canale cerca un aggiornamento. Lascia Zip + delta a meno che tu non debba forzare un tipo specifico.

Etichetta nella console	Valore CLI / API	Quali dispositivi scaricano
Zip + delta (predefinito)	all	Ogni dispositivo riceve il miglior pacchetto supportato. I dispositivi con una versione del plugin che supporta i Delta scaricano solo i file delta modificati, se presenti nel bundle. Solo i dispositivi con versioni vecchie senza supporto Delta, o i bundle caricati senza file delta, passeranno al file zip completo.
Solo zip completo	zip	Ogni dispositivo scarica l'intero zip del bundle, anche se sono presenti i file delta.
Solo Delta	delta	Solo i file delta modificati. I dispositivi con versioni vecchie del plugin senza supporto Delta riceveranno comunque lo zip completo se il bundle lo contiene.
Solo zip completo dalla build dello store	zip_from_builtin	Solo lo zip completo finché il dispositivo è sulla build dello store. Dopo il primo live update, Capgo servirà nuovamente zip + delta.
Solo Delta dalla build dello store	delta_from_builtin	Solo Delta finché il dispositivo è sulla build dello store. Dopo il primo live update, Capgo servirà nuovamente zip + delta.

Con Zip + delta, è normale vedere qualche download di zip completo. Arrivano da dispositivi che eseguono ancora una build nativa precedente con una versione del plugin senza supporto Delta (inferiore 5.10.0, 6.25.0, o 7.0.35 alla loro major version). Vedi Aggiornamenti delta.

Il build dello store sono gli asset web inclusi nel binario di App Store o Play Store, prima di qualsiasi aggiornamento Capgo. Usa una from store build only modalità quando il primo aggiornamento dopo la build dello store deve essere solo zip completo o solo delta, e gli aggiornamenti successivi possono usare entrambi.

Capgo non abbinerà un canale zip-only a un bundle delta-only, o viceversa. La console, CLI, e Canali API rifiuta il salvataggio e ti chiede di caricare il pacchetto mancante o di cambiare modalità.

Puoi impostare lo stesso valore da CLI. Il canale deve già esistere:

npx @capgo/cli@latest channel set production com.example.app --update-package zip

Valori validi: all, zip, delta, zip_from_builtin, delta_from_builtin.

Rollout progressivi

Il canale Informazioni tab include un Rollout progressivo sezione con Target del rollout e Fallback stabile, Cambia target del rollout, Applica percentuale, e azioni Completa il rollout, Rollback del rollout, Abilita il rollout, Disabilita rollout, Pausa rollout, e Riprendi il rollout.

I controlli di rollout progressivo appaiono in alto nella scheda Informazioni del canale.

Lettura Rollout progressivi prima di abilitarne uno. Quella guida copre il routing dell'upload (Auto (consigliato) / Target del rollout / Sostituisci stabile; CLI --stable / API target: "stable" per sovrascrivere), il Questo canale usa il rollout progressivo dialogo bundle-link e un workflow sicuro con Observe e Analisi dei log.

Continua da Channels

Se stai usando Canali per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow del prodotto nella Beta Testing Solution, Soluzione Version Targeting per il workflow del prodotto nella Version Targeting Solution, e Capgo Environment Best Practices: Staging con un unico Mobile App ID per il contesto pratico in Capgo Environment Best Practices: Staging con un unico Mobile App ID.