Saltare al contenuto
Capgo - Aggiornamenti in Tempo Reale per App Capacitor Capgo

Canali

Un canale di aggiornamento in tempo reale indica 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 canale di aggiornamento 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 un canale punta in qualsiasi momento e puoi anche tornare a versioni precedenti se necessario.

How a device picks a canale (precedenza)

Sezione intitolata “How a device picks a canale (precedenza)”

When a device controlla un aggiornamento, Capgo decide quale canale utilizzare in questo ordine rigoroso (priorità più alta per prima):

  1. Mapping dispositivo obbligatorio (Dashboard) – Posa manualmente un ID dispositivo specifico su 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 gli utenti QA che passano tra i canali delle feature / PR o per riprodurre un problema di utente. La reinstallazione del binario non cancella; la cancellazione dell'entry dispositivo lo fa.
  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 mostrato nell'interfaccia di sovrascrittura del dispositivo.
  1. Capacitor config defaultChannel __CAPGO_KEEP_1__ – Se presente in capacitor.config.* e non esiste alcun canale di forza/superamento/locale, l'applicazione inizia su questo canale (ad esempio, ""). Inteso per edizioni di TestFlight / interne, in modo che i tester arrivino automaticamente su un canale pre‑rilascio. Le edizioni di produzione lasciano spesso questo impostato su "". beta, qa, pr-123Canale di Default Cloud (percorso principale ~99% degli utenti)
  2. – Se segnali un canale di default nel pannello di controllo, tutti gli utenti normali (nessuna forza, nessuna sovrascrittura del pannello di controllo/__CAPGO_KEEP_0__, nessun canale locale del plugin, nessuna configurazione defaultChannel) si attaccano qui. Cambialo per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai impostazioni specifiche per piattaforma (ad esempio, uno iOS solo, uno Android solo, uno Electron solo), ogni dispositivo si attacca al default che corrisponde alla sua piattaforma. Lasciare il canale di default cloud non impostato è consentito; in quel caso il dispositivo deve corrispondere ai passaggi 1–4 per ricevere aggiornamenti. – If you mark a default channel in the dashboard, all normal end‑users (no force, no Dashboard/API override, no plugin local channel, no config defaultChannel) attach here. Change it to roll out or roll back instantly—no new binary. If you have platform-specific defaults (for example, one iOS-only, one Android-only, one Electron-only), each device lands on the default matching its platform. Leaving the cloud default unset is allowed; in that case the device must match on steps 1–4 to receive updates.

Tratta 1–4 come livelli di eccezione / testing; quando imposti un canale di default cloud, gli utenti reali dovrebbero flusso in esso. Se non scegli di impostarlo, sii deliberato su come gli utenti si attaccano (tipicamente via

  • in configurazione o sovrascritture per dispositivo). defaultChannel Configura
  • esclusivamente nei binari che spedisci esplicitamente ai tester. Lasciare non impostato mantiene la logica di produzione centralizzata nel pannello di controllo. defaultChannel Usa
  • con parsimonia in produzione—principalmente per QA o diagnostica mirata. setChannel() – Se presente in

If un 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.

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

Comportamento predefinito del canale

Sottosezione intitolata “Comportamento predefinito del canale”

Impostare un cloud predefinito è facoltativo, ma di solito serve come percorso di default per i nuovi dispositivi. 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:

  • Default unico (più comune) – Se un canale ha iOS, Android e Electron abilitati, 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 With solo iOS abilitato, android-production Con solo Android abilitato, e electron-production Con solo Electron abilitato), segnala ciascuno come predefinito per la sua piattaforma. I dispositivi iOS vanno alla configurazione predefinita iOS, i dispositivi Android vanno alla configurazione predefinita Android, e le applicazioni Electron vanno alla configurazione predefinita Electron.

Ricorda che la configurazione predefinita cloud e defaultChannel entrambi occupano lo stesso livello di decisione. Se imposti una configurazione predefinita cloud, 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 intenzionalmente ai tester o QA quando vuoi che inizino su un canale non di produzione anche se la configurazione predefinita cloud è diversa. defaultChannel Puoi modificare le impostazioni predefinite in qualsiasi momento nel pannello di controllo. Quando scambi una configurazione predefinita, i nuovi dispositivi rispettano la nuova 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'acquisizione dei dati, 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 ulteriori canali in seguito:

Setting up a Channel

  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 le prove di 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 le prove finali in un ambiente di produzione simile
  • Production - per la versione del tuo app che gli utenti finali ricevono dai negozi di app

Configurazione del Canale nell'App

Sottosezione intitolata "Configurazione del Canale nell'App"

Dopo aver creato i canali, devi configurare l'app per ascoltare il canale appropriato. In questo esempio, useremo il "canale." Development Configuring the Channel in Your App

Apri il tuo capacitor.config.ts (o capacitor.config.json) file. Sotto la plugins sezione, impostalo optionalmente defaultChannel per costruzioni di test (interno / 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.
    },
  },
};

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.

Opzioni e strategie del canale

Sezione intitolata “Opzioni e strategie del canale”

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 configurare queste dalla web app, dal CLI, o dal Public API.

  • Canale predefinito: Opzionalmente segnala i canali o le configurazioni specifiche del canale che i nuovi dispositivi si collegano a. Vedi “Comportamento del canale predefinito” per gli scenari di routing.
  • Filtri di piattaforma: Abilita o disabilita la consegna a iOS, Androido dispositivi per canale. Electron Disabilita l'aggiornamento automatico 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 gli aggiornamenti dei build di sviluppo: permette gli aggiornamenti dei build di sviluppo (utile per la verifica).
  • Consenti gli aggiornamenti dei dispositivi emulatori: permette gli aggiornamenti dei dispositivi emulatori/simulatori (utile per la verifica).
  • Consenti l'assegnazione di dispositivo auto: consente all'applicazione di passare a questo canale in esecuzione utilizzando
  • . Se disabilitato, setChannelfallirà per questo canale. setChannel Rulli progressivi

Sottosezione intitolata “Rulli progressivi”

Un canale può mantenere un pacchetto stabile mentre esporre gradualmente un obiettivo di rullaggio 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

Rulli progressivi Rulli progressivi Per il modello di consegna, flusso di lavoro del dashboard, API campi e CLI comandi.

Disabilita le strategie di aggiornamento automatico

Sottosezione intitolata “Disabilita le strategie di aggiornamento automatico”

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

  • maggiore: Blocca un bundle di destinazione la cui versione maggiore è superiore alla baseline nativa del dispositivo (version_build). Esempio: 1.2.3 -> 2.0.0 è bloccato; 1.2.3 -> 1.9.0 è consentito.
  • minore: Blocca un bundle 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 modifica al numero maggiore, minore o di patch. Sono consentite solo le modifiche 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 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: Consentire tutti gli aggiornamenti in base alla compatibilità di semver queste strategie confrontano il bundle di destinazione del canale contro la baseline nativa inviata come.

, non il bundle scaricato correntemente inviato come version_build__CAPGO_KEEP_0__ version_name.

Scopri di più dettagli e esempi in Strategia di disabilitazione degli aggiornamenti alla pagina /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

Utilizzo di setChannel() dal tuo App

Sottosezione intitolata “Utilizzo di setChannel() dal tuo App”

Il setChannel() metodo consente al tuo app di cambiare canali 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
  • Eseguimenti di flag di feature
  • Schemi di testing 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
});

Assegnare un Bundle a un Canale

Sezione intitolata “Assegnare un pacchetto a un canale”

Per distribuire un aggiornamento live, è necessario caricare un nuovo build del pacchetto JS e assegnarlo a un canale. È possibile farlo in un solo passo con il Capgo CLI:

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

Questo caricherà i tuoi asset web costruiti e stabilirà il nuovo pacchetto come build attiva per il Development canale. Gli app configurati per ascoltare quel canale riceveranno l'aggiornamento la prossima volta che controllano per uno.

È anche possibile assegnare i build ai canali dalla sezione “Pacchetti” del Capgo dashboard. Cliccare l'icona del menu accanto a un build e selezionare “Assegna a canale” per scegliere il canale per quel build.

Versionamento dei Pacchetti e dei Canali

Sezione intitolata “Versionamento dei Pacchetti e dei Canali”

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

Quando versioni i pacchetti, raccomandiamo l'utilizzo del versionamento semantico con il Capgo’s Tester Semver e identificatori pre-rilascio per costruzioni specifiche del canale. Ad esempio, un rilascio beta potrebbe essere versionato come 1.2.3-beta.1.

Questa approccio ha diversi benefici:

  • Chiaramente comunica la relazione tra le costruzioni. 1.2.3-beta.1 è ovviamente un pre-rilascio di 1.2.3.
  • Consente di riutilizzare i numeri di versione all'interno dei 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.2, ecc.
  • 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.4Utilizzo

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

Sottosezione intitolata “Ritornare indietro in un 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” del pannello di controllo:

Clicca il nome del canale che desideri tornare indietro

  1. Utilizzo
  2. Trova il build che desideri ripristinare e clicca sull'icona della corona Ripristina build
  3. Conferma l'azione

Il build selezionato diventerà immediatamente il build attivo per quel canale. Le app riceveranno la versione ripristinata la prossima volta che controllano gli aggiornamenti.

Automazione delle distribuzioni

Sottosezione intitolata “Automazione delle distribuzioni”

Per flussi di lavoro più avanzati, puoi automatizzare le distribuzioni live aggiornamenti 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 push su determinate branch o creare nuove release.

Esegui una visita ai Integrazione CI/CD documenti per imparare di più sull'automazione degli aggiornamenti live Capgo.

Previsualizzazioni di PR con privilegi minimi

Sottosezione intitolata “Previsualizzazioni di PR con privilegi minimi”

Usa un Anteprima dell'app API chiave quando il CI ha bisogno 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; 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, scoping per canale.

  1. Hai un amministratore dell'organizzazione che crea una chiave di API sicura limitata all'app di anteprima e seleziona Anteprima dell'app. Vedi Chiavi di API.
  2. Usa un canale unico, non pubblico come pr-123. Non passare --default, --self-assign, opzioni di rollout o --delete-linked-bundle-on-upload.
  3. Carica e promuovi il bundle della PR in un comando, poi elimina il canale e il bundle di proprietà quando la PR si chiude:
Finestra del terminale
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 da proprietario: la chiave può cancellare solo un canale che ha creato e il suo pacchetto correlato, 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 impostare 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 identico con github.event.pull_request.head.repo.full_name == github.repository.

Distribuire su un dispositivo

Sezione intitolata “Distribuire su un dispositivo”

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 nel tuo app
  2. Configura l'app per ascoltare il canale desiderato
  3. Carica una build e assegna il canale a quella
  4. Lancia l'app e attendi l'aggiornamento!

Per una guida dettagliata, consulta il Deploying Live Updates aggiornamento in tempo reale. Buon aggiornamento!

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 un potente strumento per la segmentazione degli utenti, che consente di attivare funzionalità come:

  • Flag di funzionalità per diversi livelli di utenti
  • Test A/B
  • Rilascio graduale di nuove funzionalità
  • Programmi di test beta

Impara a 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

Sezione intitolata “Continua da Canali”

Se stai utilizzando Canali per pianificare la routing dei canali e la distribuzione in fasi, 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: Staging con un ID di App Mobile per il contesto pratico in Capgo Pratiche per l'ambiente: Staging con un ID di App Mobile.