Saltare al contenuto

Canali

Un canale di Aggiornamenti in tempo reale punta a una specifica versione del pacchetto JS 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 un 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)”

When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):

  1. Mappatura forzata del dispositivo (Dashboard) – Pianifica un ID dispositivo specifico su un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo sempre vince.
  2. Cloud override (per‑device) via Dashboard or API – Created when you change the device’s channel in the dashboard or via API. Use for QA users switching between feature / PR channels or to reproduce a user issue. Reinstalling the binary does not clear it; deleting the device entry does.
  3. 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 immediatamente e non viene visualizzato nell'interfaccia di sovrapposizione del dispositivo.
  1. Capacitor config defaultChannel (test build default) – Se presente in capacitor.config.* e non esiste alcun canale forzato/override/locale, l'app inizia su questo canale (ad esempio) beta, qa, pr-123Inteso per TestFlight / costruzioni interne affinché i tester si trovino automaticamente su un canale di anteprima. Le costruzioni di produzione lasciano spesso questo impostato su "nessuno".
  2. Canale di default Cloud (percorso principale ~99% degli utenti) – Se segni un canale di default 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. Modificare il canale di default consente di distribuire o ritirare immediatamente – senza nuovo binario. Se hai impostazioni predefinite per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo si attacca al canale predefinito che corrisponde alla sua piattaforma. Lasciare il canale di default cloud non impostato è consentito; in tal caso il dispositivo deve corrispondere ai passaggi 1-4 per ricevere aggiornamenti.

Pratica consigliata:

  • Tratta 1-4 come layer di eccezione/test; quando imposti un canale di default, gli utenti reali dovrebbero flusso in esso. Se non scegli di impostarlo, sii deliberato su come gli utenti si attaccano (tipicamente tramite) defaultChannel Configura solo
  • nei binari che spedisci esplicitamente ai tester. Lasciare il campo vuoto mantiene la logica di produzione centralizzata nel pannello di controllo. defaultChannel Utilizza
  • – Se presente in setChannel() sparso 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 > Config defaultChannel > Impostazione predefinita Cloud.

Impostare un'impostazione predefinita cloud è facoltativo, ma di solito serve come percorso di riserva per i nuovi dispositivi. Senza una di queste, solo i dispositivi che corrispondono alle mappature forzate, agli override o a una defaultChannel in Capacitor config riceveranno gli aggiornamenti. Quando scegli di segnalare i valori predefiniti, tieni presente:

  • Impostazione predefinita singola (più comune) – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico valore predefinito; qualsiasi dispositivo senza override si attaccherà qui.
  • Impostazioni predefinite specifiche per piattaforma – Se si suddividono 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), 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 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. Quando cambiate un default, i nuovi dispositivi seguono le nuove regole di routing immediatamente e gli dispositivi esistenti seguono le normali regole di precedenza la prossima volta che controllano.

Configurazione di un Canale

Sezione intitolata “Configurazione di un Canale”

– If you split channels by platform (for example,

Durante l'acquisizione, 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 Capgo dashboard
  2. Clicca sul pulsante “Nuovo Canale”
  3. Inserisci un nome per il canale e clicca su “Crea”

I nomi dei canali possono essere qualsiasi cosa tu voglia. Una strategia comune è di corrispondere i canali alle tue fasi di sviluppo, ad esempio:

  • Development - per testare gli aggiornamenti live sui dispositivi locali o sugli emulatori
  • QA - per il tuo team di QA per verificare gli aggiornamenti prima della larga diffusione
  • Staging - per il test finale in un ambiente simile alla produzione
  • Production - per la versione del tuo app che gli utenti finali ricevono dai negozi di 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, opzionalmente impostare defaultChannel per build di test interni / QA). Per i build 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.
},
},
};

Successivamente, 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.

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. Potete configurarle dall'app web, dal CLI, o dal Public API.

  • Canale predefinito: Opzionalmente segnate i canali o le impostazioni specifiche del canale che i nuovi dispositivi si connettono. Vedere “Comportamento del canale predefinito” per gli scenari di routing.
  • Filtri di piattaforma: Abilita o disabilita la consegna a iOS, Androido Electron dispositivi per canale.
  • Disabilita l'auto downgrade sotto nativo: Impedisce di inviare un aggiornamento quando la versione nativa del dispositivo è più recente della bundle del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
  • Consenti aggiornamenti di build di sviluppo: Consentire aggiornamenti a build di sviluppo (utile per la prova).
  • Consenti dispositivi emulator: Consentire aggiornamenti a emulator/simulatore (utile per la prova).
  • Consenti l'assegnazione di dispositivo auto: Lascia che l'app si passi a questo canale in esecuzione utilizzando setChannel. Se disabilitato, setChannel fallirà per questo canale.

Un canale può mantenere una bundle stabile mentre esporre gradualmente un obiettivo di rollout separato a un gruppo di dispositivi adesivi. Puoi fermare, riprendere, promuovere, tornare indietro e configurare una risposta di fallimento automatica senza cambiare il canale per tutti. Vedi Rilasci progressivi per il modello di consegna, flusso di lavoro del dashboard, API campi e CLI comandi.

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

  • maggiore: Blocca un pacchetto di destinazione con una versione maggiore rispetto alla baseline nativa del dispositivo (version_buildEsempio: 1.2.3 -> 2.0.0 è bloccato; 1.2.3 -> 1.9.0 è consentito.
  • minore: Blocca un pacchetto di destinazione con una versione maggiore o minore rispetto a version_buildEsempio: 1.2.3 -> 1.3.0 è bloccato; 1.2.3 -> 1.2.4 è consentito.
  • patch: Modalità più rigorosa. Blocca qualsiasi modifica al numero maggiore, minore o di patch. Sono consentite solo le modifiche ai suffissi. MAJOR.MINOR.PATCH rimane 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: Richiede una versione minima di aggiornamento di metadati su ogni bundle. Configurare tramite CLI usando --min-update-version o --auto-min-update-versionSe mancante, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non viene impostato.
  • nessuno: Consentire tutti gli aggiornamenti secondo la compatibilità di semver Queste strategie confrontano il bundle di destinazione del canale con la baseline nativa inviata come.

compatibilità di semver version_buildNon il bundle scaricato attualmente inviato come version_name.

Saperne di più dettagli e esempi in Disable updates strategy a /docs/cli/commands/#disable-updates-strategy.

Esempio (CLI):

Fenestra del terminale
# 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

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

  • Menu di debug/QA dove gli tester possono cambiare tra canali
  • Flussi di opzione per il programma beta
  • Eseguimenti di flag 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
});

Per distribuire un aggiornamento in tempo reale, è necessario caricare una nuova build del bundle JS e assegnarla a un canale. Ciò può essere fatto in un solo passo con il Capgo CLI:

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

Ciò 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.

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

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

Quando versioni i tuoi bundle, consigliamo di utilizzare Aggiornamenti di versione semantica con Capgo’s Tester di Semver e identificatori di rilascio pre-anteprima per edizioni specifiche del canale. Ad esempio, un rilascio beta potrebbe essere versionato come 1.2.3-beta.1.

In CI, se la versione locale era già caricata, utilizzare npx @capgo/cli@latest bundle upload --auto-bump (facoltativamente major, minor, patch/fix, metadata, o ai) in modo che CLI aumenti dal pacchetto collegato del canale fino a trovare un nome libero. Con ai, Workers AI inferisce il livello dal manifesto locale vs precedente delta (ricade su patch con nessuna versione precedente Capgo). Non è possibile combinarlo con --bundle. Vedi e il __CAPGO_KEEP_0__ di riferimento CLI reference.

Questa approccio ha diversi benefici:

  • Comunica chiaramente la relazione tra le build. 1.2.3-beta.1 è ovviamente una versione pre-rilascio di 1.2.3.
  • Consente di riutilizzare i numeri di versione across canali, riducendo la confusione.
  • Consente percorsi di rollback chiari. Se hai bisogno di tornare indietro da 1.2.3sai 1.2.2 è la versione stabile precedente.

Ecco un esempio di come potresti allineare le versioni dei tuoi 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.2, ecc.
  • Production canale: 1.2.3, 1.2.4, ecc.

Utilizzo semver con identificatori di rilascio prenotificati è 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 indietro una Aggiornamento in Tempo Reale

Sezione intitolata “Ritornare indietro un Aggiornamento in Tempo Reale”

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

  1. Clicca il nome del canale che desideri tornare indietro
  2. Cerca la versione che desideri annullare e clicca l'icona della corona Ripristina costruzione
  3. Conferma l'azione

Il costruito selezionato diventerà immediatamente la costruzione attiva per quel canale di nuovo. Le app riceveranno la versione ripristinata la prossima volta che controllano gli aggiornamenti.

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

Esegui la consultazione dei Integrazione CI/CD docs to learn more about automating Capgo live updates.

documenti per imparare di più sull'automazione degli aggiornamenti live __CAPGO_KEEP_0__.

Previsualizzazioni PR con privilegi minimi

Sottosezione intitolata “Previsualizzazioni PR con privilegi minimi” Anteprima dell'app La chiave API viene utilizzata quando il CI necessita di una 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; essa semplicemente non ha alcun ruolo organizzativo. Ogni canale di anteprima non pubblico che crea riceve la propria autorizzazione di ciclo di vita automatica, scoping per canale.

  1. Creare un amministratore di organizzazione una chiave sicura API limitata all'app di anteprima e selezionare Anteprima dell'appVedi Chiavi API.
  2. Utilizzare un canale unico e non pubblico come pr-123Non passare --default, --self-assignopzioni di rilascio o --delete-linked-bundle-on-upload.
  3. Carica e promuovi il bundle della PR in un comando, poi cancella il canale e il bundle di proprietà quando la PR si chiude:
Fermata di sistema
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 pacchetto e lo promuove in un flusso unico. La pulizia è atomica e controllata dall'accesso: la chiave può cancellare solo un canale che ha creato e il suo pacchetto collegato, non condiviso. Non può cambiare, promuovere o cancellare un canale principale/di default esistente, un canale di un'altra chiave di anteprima o un pacchetto 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:

Finestra del terminale
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 possibilità di modificare le 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.

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

  1. Installa il Capgo SDK nella tua app
  2. Configura l'app per ascoltare il tuo canale desiderato
  3. Carica un build e assegna il canale a cui appartiene
  4. Lancia l'app e attendi l'aggiornamento!

Per una guida dettagliata, consulta il Deploying Live Updates guide. Buon aggiornamento!

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

  • Flag di feature per diversi livelli di utenti
  • Test A/B
  • Rollout graduale delle feature
  • Programmi di testing beta

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

Se stai utilizzando Canali Per pianificare la routing dei canali e il rilascio in fasi, connettilo con Canali Per i dettagli di implementazione in Canali, Per i dettagli di implementazione in Canali, Soluzione di testing beta Soluzione di testing beta per il workflow del prodotto nella Soluzione di Test Beta Versione Targeting Solution per il workflow del prodotto nella Soluzione di Targeting Versione, e Capgo Pratiche per l'ambiente Migliori: Staging con un ID App Mobile per il contesto pratico in Capgo Pratiche per l'ambiente Migliori: Staging con un ID App Mobile.