Canali

Un canale di aggiornamento in tempo reale punta a una specifica versione di build 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 di build a cui punta il canale in qualsiasi momento e puoi anche tornare a versioni precedenti se necessario.

Canali non forniscono confidenzialità

Canali controllano l'eligibilità degli aggiornamenti, non la segretezza del pacchetto. Anche se un canale è privato o è disabilitata l'assegnazione auto, qualsiasi pacchetto non crittografato caricato su Capgo dovrebbe ancora essere trattato come un asset pubblico consegnato ai clienti. La crittografia protegge il percorso di consegna e l'autenticità degli aggiornamenti, ma i pacchetti consegnati possono ancora essere ricostruiti a partire dall'applicazione distribuita con sufficiente sforzo perché la chiave pubblica fa parte del client. Vedi Aggiornamento in tempo reale crittografato per i dettagli.

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):

1. Mapping forzato del dispositivo (Dashboard) – Pina manualmente un ID dispositivo specifico a un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo sempre vince.
2. 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'ingresso del dispositivo si cancella.

Sostituisci il canale in modo istantaneo con setChannel()

A partire dalla versione del plugin 5.34.0, 6.34.0, 7.34.0 o 8.0.0 (a seconda della tua versione principale), setChannel() funziona in modo diverso: contatta il backend per verificare se il canale è consentito (verifica se l'assegnazione auto è abilitata per quel canale), quindi memorizza il canale localmente sul dispositivo come defaultChannelQuesto significa che il nuovo canale ha effetto istantaneamente per la prossima verifica degli aggiornamenti—nessuna attesa per la replica.

In precedenza, setChannel() ha salvato l'override del canale nel database backend (come Dashboard o API modifiche), e i dispositivi dovevano attendere la replicazione 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 transizioni tra canali istantanee.

Nota: Anche se un canale diventa non consentito dopo essere stato impostato localmente, il backend ancora valuterà il canale durante i controlli di aggiornamento, quindi la sicurezza è mantenuta.

Importante: Quando le modifiche ai canali vengono effettuate tramite il Dashboard o API, è ancora presente un ritardo di replicazione di fino a 2 minuti prima che tutti i server di edge riflettano il cambiamento. Per una transizione istantanea tra canali, utilizzare setChannel() dal tuo app code—valida con il backend, quindi imposta il canale localmente per un effetto immediato.

3. Capacitor config defaultChannel (costruzione di test predefinita) – Se presente in capacitor.config.* e non esiste un forzatura/override, l'app si avvia su questo canale (ad esempio, beta, qa, pr-123). Inteso per le costruzioni di TestFlight / interni affinché i tester atterrino su un canale di anteprima automaticamente. Le costruzioni di produzione lasciano spesso questo impostato su impostazione predefinita.
4. Canale predefinito Cloud (percorso principale ~99% degli utenti) – Se segnali un canale predefinito nella dashboard, tutti gli utenti normali (nessun forzamento, nessuna sovrascrittura, nessuna configurazione predefinita del canale) si attaccano qui. Cambialo per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai impostazioni predefinite specifiche per piattaforma (ad esempio, uno iOS solo, uno Android solo, uno Electron solo), ogni dispositivo si attacca al predefinito che corrisponde alla sua piattaforma. Lasciare il predefinito cloud non impostato è consentito; in quel caso il dispositivo deve corrispondere ai passaggi 1–3 per ricevere aggiornamenti.

Pratica consigliata:

• Tratta 1–3 come eccezioni / layer di testing; quando imposti un predefinito cloud, gli utenti reali dovrebbero flusso in esso. Se non scegli di impostarlo, essere deliberato su come gli utenti si attaccano (tipicamente via defaultChannel in configurazione o sovrascritture per dispositivo).
• Configura solo defaultChannel in binari che spedisci esplicitamente ai tester. Lasciare non impostato mantiene la logica di produzione centralizzata nella dashboard.
• 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 nella lista.

Riepilogo: Forza > Sovrascrittura > Config defaultChannel > Predefinito cloud.

Comportamento del canale predefinito

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

• Valore predefinito singolo (più comune) – Se un canale ha abilitato iOS, Android e Electron, diventa il valore predefinito unico; qualsiasi dispositivo senza override si attaccherà qui.
• Valori predefiniti specifici per piattaforma – Se si suddivide i canali per piattaforma (ad esempio ios-production con solo iOS abilitato android-production con solo Android abilitato, e electron-production con solo Electron abilitato), segnala ogni canale come valore predefinito per la sua piattaforma. I dispositivi iOS vanno al valore predefinito iOS, i dispositivi Android vanno al valore predefinito Android e le applicazioni Electron vanno al valore predefinito Electron.

Ricorda che il valore predefinito del cloud e defaultChannel in capacitor.config.* entrambi occupano lo stesso livello di decisione. Se imposti un cloud predefinito, non hai bisogno di duplicare il valore nella tua Capacitor configurazione—lascia defaultChannel vuoto per le costruzioni di produzione. Riserva defaultChannel per i binari che intendi spedire intenzionalmente ai tester o QA quando vuoi che inizino su un canale non di produzione anche se il cloud predefinito è diverso.

Puoi modificare i valori predefiniti in qualsiasi momento nel dashboard. Quando scambi un valore predefinito, i dispositivi nuovi rispettano le nuove impostazioni di routing immediatamente e i dispositivi esistenti seguono le normali regole di precedenza la prossima volta che si connettono.

Configurazione di un Canale

Durante l'accesso iniziale 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:

1. Vai alla sezione “Canali” del tuo Capgo dashboard
2. Clicca sul pulsante “Nuovo Canale”
3. Inserisci un nome per il canale e clicca su “Crea”

Il nome del canale può essere qualsiasi cosa tu voglia. Una strategia comune è di sincronizzare i canali con le tue fasi di sviluppo, ad esempio:

• Development - per testare aggiornamenti live su dispositivi locali o emulatori
• QA - per il team QA per verificare gli aggiornamenti prima della rilascio più ampio
• Staging - per il testing finale in un ambiente di produzione simile
• Production - per la versione dell'app che gli utenti finali ricevono dai negozi di app

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, imposta optionalmente il defaultChannel per test builds (internazionale / 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.
    },
  },
};

Costruisci successivamente 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.

Attenzione

Ordine di selezione del canale: Forza > Override (setChannel / dashboard) > Config defaultChannel > Cloud Default.

Usa defaultChannel solo nelle costruzioni di test/internazionale; lascialo fuori per la produzione in modo che gli utenti seguano il Cloud Default (se impostato) invece di duplicare la routing nella configurazione nativa.

You potresti ancora forzare (bloccare) un dispositivo o applicare un sovrapposizione in un secondo momento—quelle hanno la precedenza immediata sul valore di configurazione.

Il nome del canale è case sensitive.

Opzioni e strategie del canale

Il canale ha 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 canalizzazioni specifiche per piattaforma che i nuovi dispositivi si collegano a. Vedi “Comportamento del canale predefinito” per scenari di routing.
• Filtro per piattaforma: Abilita o disabilita la consegna a iOS, Android, o Electron dispositivi per canale.
• Disabilita l'auto downgrade sotto nativo: Impedisce di inviare un aggiornamento quando la versione dell'app nativa del dispositivo è più recente della bundle del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
• Consenti costruzioni di sviluppo: Consentire aggiornamenti alle costruzioni di sviluppo (utile per i test).
• Consenti dispositivi emulatori: Consentire aggiornamenti ai dispositivi emulatori/simulatore (utile per i test).
• Consenti l'assegnazione di dispositivo: consente all'app di passare a questo canale in esecuzione in tempo reale utilizzando setChannel. Se disabilitato, setChannel fallirà per questo canale.

Disabilita le strategie di aggiornamento automatico

Utilizza questo per limitare quali tipi di aggiornamenti il canale consegnerà automaticamente. Opzioni:

• maggiore: Blocca gli aggiornamenti intermajor (0.0.0 → 1.0.0). Gli aggiornamenti minori e di patch sono ancora consentiti.
• minore: Blocca gli aggiornamenti interminor (ad esempio, 1.1.0 → 1.2.0) e maggiori. Gli aggiornamenti di patch sono ancora consentiti. Nota: non blocca 0.1.0 → 1.1.0.
• patch: Molto rigoroso. Consente solo l'aumento delle versioni di patch all'interno della stessa versione maggiore e minore. Esempi: 0.0.311 → 0.0.314 ✅, 0.1.312 → 0.0.314 ❌, 1.0.312 → 0.0.314 ❌.
• metadata: Richiedi una versione minima di aggiornamento di metadati 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.
• none: Consentisci tutti gli aggiornamenti in base alla compatibilità semver.

Scopri ulteriori dettagli e esempi nella strategia di disabilitazione degli aggiornamenti alla sezione /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 canale in modo programmatico durante l'esecuzione. Ciò è 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
• A/B testing scenari

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
});

Come funziona setChannel() (v5.34.0+ / v6.34.0+ / v7.34.0+ / v8.0.0+)

Quando setChannel() è chiamato:

1. Validazione backend (solo lettura): Viene inviata una richiesta al backend Capgo per verificare se il canale è consentito (verificando le autorizzazioni di assegnazione auto)
2. Aggiornamento del storage locale: Se la validazione ha successo, il canale viene salvato nel storage locale del dispositivo come defaultChannel
3. Effetto immediato: La prossima verifica dell'aggiornamento utilizza il nuovo canale immediatamente (nessuna attesa per la replica)

Perché conta: In versioni precedenti, setChannel() salvava l'override del canale nel database backend (lo stesso di Dashboard o API modifiche). I dispositivi dovevano attendere la replica del backend (fino a 2 minuti) prima che il cambio del canale avesse effetto. Ora, setChannel() legge solo dal backend (per la validazione) e memorizza localmente, rendendo i cambiamenti di canale istantanei.

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à comunque il canale durante le verifiche di aggiornamento, garantendo la sicurezza.

Confronto dei metodi di cambio del canale:

Metodo	Tempo di effetto	Persistente dove	Utilizzo
setChannel() dal plugin	__CAPGO_KEEP_0__	Solo dispositivo (locale)	Spostamento del canale inizializzato dall'utente all'interno dell'app
Impostazione del dispositivo del pannello di controllo	Fino a 2 min	Database backend	Modifiche inizializzate dall'amministratore per dispositivi specifici
API assegnazione del canale	Fino a 2 min	Database backend	Integrazioni backend automatizzate

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

Versioni minime per il canale di sola lettura: 5.34.0, 6.34.0, 7.34.0o 8.0.0 (in base alla tua versione maggiore). Ogni numero di versione minore corrisponde allo stesso set di funzionalità per tutte le versioni maggiori (ad esempio, X.34.0 include lo stesso set di 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 deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the Capgo CLI:

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

Questo Development canale. Qualsiasi app configurata per ascoltare quel canale riceverà l'aggiornamento la prossima volta che lo cercherà.

Puoi anche assegnare le build ai canali dalla sezione “Bundles” 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

È 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 il versionamento semantico semver con identificatori di pre-uscita per le build specifiche dei canali. Ad esempio, una versione beta potrebbe essere versionata come 1.2.3-beta.1.

Questa approccio ha diversi vantaggi:

• È chiaro che comunica la relazione tra le build. 1.2.3-beta.1 è ovviamente una pre-uscita di 1.2.3.
• Consente di riutilizzare i numeri di versione across canali, riducendo la confusione.
• Consente di avere percorsi di rollback chiari. Se hai bisogno di tornare indietro da 1.2.3sei sicuro 1.2.2 è la versione precedente di rilascio stabile.

Ecco un esempio di come potresti allineare le versioni del tuo bundle con un setup di canale tipico:

• Development canale: 1.2.3-dev.1, 1.2.3-dev.2ecc.
• QA canale: 1.2.3-qa.1, 1.2.3-qa.2ecc.
• Staging canale: 1.2.3-rc.1, 1.2.3-rc.2ecc.
• Production canale: 1.2.3, 1.2.4ecc.

Utilizzare semver con identificatori di versione pre-release è 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 all'aggiornamento in tempo reale

Se hai distribuito un aggiornamento in tempo reale che introduce un bug o che deve essere annullato, puoi facilmente tornare a una versione precedente. Dalla sezione “Canali” della dashboard:

1. Clicca sul nome del canale che vuoi tornare indietro
2. Trova la versione che vuoi annullare e clicca sull'icona della corona
3. Conferma l'azione

La versione selezionata diventerà immediatamente la versione attiva per quel canale. Gli app riceveranno la versione ritornata la prossima volta che controllano per un aggiornamento.

Automatizzare le distribuzioni

Per flussi di lavoro più avanzati, puoi automatizzare le tue distribuzioni di aggiornamento 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.

Ecco il modo di fare Integrazione CI/CD consultate le doc per imparare di più su come automatizzare gli aggiornamenti Capgo in tempo reale.

Distribuzione su un Dispositivo

Ora che hai capito i canali, sei pronto a iniziare a distribuire gli aggiornamenti in tempo reale su dispositivi reali. Il processo base è:

1. Installa il Capgo SDK nel tuo app
2. Configura l'app per ascoltare il tuo canale desiderato
3. Carica una build e assegna il canale a quella
4. Lancia l'app e aspetta l'aggiornamento!

Per una guida dettagliata, consulta la sezione Distribuzione Aggiornamenti in Tempo Reale guide. Aggiornamento felice!

Utilizzo avanzato dei canali: segmentazione degli utenti

I canali possono essere utilizzati per più di solo le fasi di sviluppo. Sono uno strumento potente per la segmentazione degli utenti, che consente di attivare funzionalità come:

• Flag di feature per diversi livelli di utenti
• Test A/B
• Rilascio graduale di nuove funzionalità
• 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 flag di feature e i test A/B.