Saltare al contenuto
Capgo - Costruisci, distribuisci e aggiorna Capacitor app Capgo

Canali

Un canale Live Update punta a una specifica build del pacchetto JS del tuo app che verrà condivisa con qualsiasi dispositivo configurato per ascoltare quel canale per le aggiornamenti. Quando installi il Capgo Live Updates SDK nel tuo app, qualsiasi binario nativo configurato per quel canale controlla per aggiornamenti disponibili ogni volta che l'app viene avviata. Puoi modificare la build a cui punta un canale in qualsiasi momento e puoi anche tornare a precedenti build se necessario.

Come un dispositivo sceglie un canale (precedenza)

Sezione intitolata “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. Assegnazione forzata del dispositivo (Dashboard) – Assegna manualmente un ID dispositivo specifico a un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo vince sempre. Capgo elimina la mappatura dopo 90 giorni dall'ultima scrittura di override. Vedi Console e API override scadono dopo 90 giorni.
  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 di feature / PR o per riprodurre un problema di utente. La reinstallazione del binario non lo cancella; la cancellazione dell'override del dispositivo lo fa. La stessa conservazione di 90 giorni si applica.
  3. Plugin setChannel() Canale locale – Crea quando l'applicaazione 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.
  1. Capacitor configurazione defaultChannel (costruzione di test predefinita) – Se presente in capacitor.config.* e non esiste un canale forzato/sovrascrittura locale, l'app inizia su questo canale (ad esempio beta, qa, pr-123Inteso per TestFlight / costruzioni interne, in modo che i tester siano automaticamente indirizzati a un canale di anteprima. Le costruzioni di produzione lasciano questo campo invariato.
  2. Canale predefinito Cloud (percorso principale ~99% degli utenti) – Se segnali un canale predefinito nel pannello di controllo, tutti gli utenti normali (nessun forzamento, nessuna sovrascrittura del pannello di controllo/API, nessuna plugin locale, nessuna configurazione predefinita del canale) si attaccano qui. Modificare per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai impostazioni predefinite per piattaforma (ad esempio, uno iOS solo, uno Android solo, uno Electron solo), ogni dispositivo atterra sul 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:

  • Trovare 1-4 come livelli di eccezione/test; quando imposti un canale predefinito cloud, gli utenti reali dovrebbero flusso in esso. Se non lo imposti, sii deliberato su come gli utenti si attaccano (tipicamente tramite 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 dashboard.
  • Usa setChannel() raramente in produzione—principalmente per le prove di qualità o i diagnosi mirati.

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 > Dashboard/API Override > Plugin setChannel() canale locale > Config defaultChannel > Impostazione Cloud predefinita.

Console e API override scadono dopo 90 giorni

Sezione intitolata “Console e API override scadono dopo 90 giorni”

Per le mappature obbligatorie e per i canali Dashboard o pubblici API sono memorizzati gli assegnamenti per dispositivo in Capgo. Un lavoro di pulizia elimina questi assegnamenti. 90 giorni dopo l'ultima scrittura di overrideControlla l'aggiornamento non resettare il cronometro. Solo scrivere nuovamente l'override (o cancellarlo tu stesso) modifica la data e l'ora.

Questo non è lo stesso di inventario dei dispositiviInventario rimuove i dispositivi che non si sono collegati a Capgo per 90 giorni. La pulizia dell'override rimuove la mappatura anche se il dispositivo è ancora attivo.

Per un'assegnazione che non viene rimossa da questa pulizia:

  • Imposta defaultChannel in capacitor.config.* (resiste alla reinstallazione; richiede un nuovo binario nativo per cambiare in seguito).
  • Chiamare setChannel() dalla app. A partire da plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 e successive versioni, quella assegnazione è locale e non viene rimossa da questa pulizia. Riinstallando l'app, la si cancella, quindi l'app deve chiamare setChannel() nuovamente se desideri ancora quel canale.

Il canale Dispositivi tab e il dispositivo Override UI solo elenca console e assegnazioni pubbliche API. Non elencano ogni dispositivo sul canale e non elencano dispositivi locali setChannel() assignments.

Canale Capgo dispositivo scheda dispositivi mostrando il popover di sovrascrittura della conservazione: le sovrascritture console scadono dopo 90 giorni
Notifica di conservazione sovrascritta sulla scheda dispositivi del canale.

Sottosezione intitolata “Comportamento del Canale Predefinito”

Comportamento del canale predefinito

Setting a cloud default is optional, but it usually serves as the catch-all path for new devices. Without one, only devices that match on forced mappings, overrides, or a defaultChannel Nelle impostazioni del Capacitor config verranno ricevute le aggiornamenti. Quando scegli di segnalare i valori di default, tieni presente questi pattern:

  • Default specifici per piattaforma – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico predefinito; qualsiasi dispositivo senza sovrascritture si attaccherà qui.
  • Default specifici per piattaforma – Se si suddividono i canali per piattaforma (ad esempio, ios-production con iOS abilitato solo, android-production con Android abilitato solo, e electron-production con Electron abilitato solo), segnalare ogni uno come predefinito per la sua piattaforma. Gli dispositivi iOS vanno al canale iOS predefinito, gli Android vanno al canale Android predefinito, e le applicazioni Electron vanno al canale Electron predefinito.

Ricordate che il predefinito cloud e defaultChannel in capacitor.config.* entrambi occupano lo stesso livello di decisione. Se si imposta un predefinito cloud, non è necessario duplicare il valore nella configurazione Capacitor— lasciare defaultChannel vuoto per le costruzioni di produzione. Riservare defaultChannel per i binari che si intendono inviare ai tester o QA quando si desidera che inizino su un canale non di produzione anche se il predefinito cloud è diverso.

È possibile modificare i predefiniti in qualsiasi momento nel pannello di controllo. Aprire il canale, poi Gestisci le impostazioni dell'app, che ti porta a Informazioni sull'app. L'impostazione predefinita non è più un toggle sulla pagina del canale. Quando sostituisci una impostazione predefinita, 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

Sezione intitolata “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 ulteriori canali 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 canali possono avere nomi che piacciono a voi. Una strategia comune è associare i canali alle fasi di sviluppo, ad esempio:

  • Development - per testare gli aggiornamenti live sui dispositivi locali o sui simulatori
  • QA per la verifica del vostro team QA prima della versione più ampia
  • Staging - per il test finale in un ambiente simile alla produzione
  • Production - per la versione dell'app che gli utenti finali ricevono dai negozi di app

Configura il canale nell'app

Sottosezione intitolata “Configura il canale nell'app”

Una volta creati i canali, è necessario configurare l'app per ascoltare il canale appropriato. In questo esempio, utilizzeremo il Development canale.

Apre il capacitor.config.ts (o capacitor.config.jsonfile. Sotto la plugins sezione, configurabile facoltativamente defaultChannel for per (Interno / QA). Per le build di produzione, preferisci ometterlo in modo che i dispositivi utilizzino il Cloud Default a meno che non venga sovrascritto esplicitamente.

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

Ecco, costruisci il tuo'app web e eseguila npx cap sync per copiare il file di configurazione aggiornato nei tuoi progetti iOS, Android ed Electron. Se salti questo passaggio di sincronizzazione, i tuoi progetti nativi continueranno ad utilizzare il canale su cui erano configurati precedentemente.

Opzioni e strategie del canale

Titolo della sezione “Opzioni e strategie del canale”

I canali hanno diverse opzioni che controllano chi può ricevere aggiornamenti e come vengono consegnati. Le più importanti sono quelle elencate di seguito. Puoi configurarle dall'app web, dal CLI, o dal Public API.

  • Canale predefinito: Opzionalmente segnala il canale o i canali specifici per piattaforma che i nuovi dispositivi si connettono. Nel console vive su App Information (Gestisci le impostazioni dell'app da pagina del canale). Vedi “Comportamento del canale predefinito” per scenari di routing.
  • Filtro per piattaforma: Abilita o disabilita la consegna a iOS, Android, or Electron dispositivi per canale.
  • Disable auto downgrade under native: Prevents sending an update when the device’s native app version is newer than the channel’s bundle (for example, device on 1.2.3 while channel has 1.2.2).
  • Permettere aggiornamenti di build di sviluppo: Consentire aggiornamenti ai build di sviluppo (utili per le prove). CLI: --dev / --no-dev.
  • Allow production builds: Permit updates to production (store) builds. Leave this on for channels that serve real users. CLI: --prod / --no-prod.
  • Consenti dispositivi emulatori: Consentire aggiornamenti ai dispositivi emulatore/simulatore (utile per i test). CLI: --emulator / --no-emulator.
  • Consenti dispositivi fisici: Consentire aggiornamenti ai telefoni e tablet reali. Lascia questo attivo per i canali di produzione. CLI: --device / --no-device.
  • Allow device self-assignment: Lets the app switch to this channel at runtime using setChannelSe disabilitato, setChannel fallirà per questo canale. CLI: --self-assign / --no-self-assign.
  • Formato di download: Scegli se i dispositivi scaricano un file zip completo, solo i file delta modificati o il meglio di entrambi (all, zip, delta, zip_from_builtin, delta_from_builtinvedi Formato di download per il menu a discesa del console e quando ogni modalità è utile.

Rollout progressivi

Sezione intitolata “Rullaggi progressivi”

Page/area: Pagina di marketing delle soluzioni Capgo. Ruolo: Etichetta di navigazione breve o elemento UI. Visualizzato in: pagina solutions/cordova-to-capacitor.astro. Chiave messaggio `solutions_cordova_to_capacitor_link_rollouts` (Solutions Cordova To Capacitor Link Rollouts). Rilasci progressivi per il modello di consegna, flusso di lavoro del dashboard, API campi e CLI comandi.

Disabilita strategie di aggiornamento automatico

Sezione intitolata “Disabilita strategie di aggiornamento automatico”

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

  • maggiore: Blocca un bundle 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 bundle 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ù restrittiva. 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: Richiedi una versione minima di aggiornamento di metadati per ogni bundle. Configurare tramite CLI utilizzando --min-update-version o --auto-min-update-versionSe manca, il canale viene segnalato come non configurato e gli aggiornamenti saranno rifiutati fino a quando non viene impostato.
  • nessuno: Consentire tutti gli aggiornamenti secondo compatibilità semver.

Queste strategie confrontano il bundle di destinazione del canale con la baseline nativa inviata come version_build, non il bundle scaricato attualmente inviato come version_name.

Scopri ulteriori dettagli e esempi nella strategia di disabilitazione degli aggiornamenti in /docs/cli/commands/#disable-updates-strategy.

Esempio (CLI). Il canale deve già esistere (channel set Non crea (it):

Fermata 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


# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

Utilizzando setChannel() dal tuo App

Sottosezione intitolata “Utilizzando setChannel() dal tuo App”

La setChannel() metodo consente al tuo app di cambiare canali in esecuzione in tempo reale. Ciò è particolarmente utile per:

  • menu di debug/QA dove gli tester possono cambiare tra canali
  • flussi di opzione per il programma beta
  • Implementazioni delle bandiere di feature
  • Scenari 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
});

Assegnazione di un Bundle a un Canale

Sottosezione intitolata “Assegnazione di un Bundle a un Canale”

Per distribuire un live update, è necessario caricare un nuovo build del bundle JS e assegnarlo a un canale. Puoi farlo in un passo con il Capgo CLI:

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

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

Puoi anche assegnare le build ai canali dalla sezione “Pacchetti” del tuo Capgo dashboard. Clicca sull'icona del menu accanto a una build e seleziona “Assegna al canale” per scegliere il canale per quella build.

Versionamento dei Pacchetti e Canali

Sezione intitolata “Versionamento dei Pacchetti e Canali”

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

Quando versioni i pacchetti, consigliamo di utilizzare la versioning semantico con il Capgo Semver Tester E identificatori di pre-uscita per edizioni specifiche del canale. Ad esempio, una versione beta potrebbe essere versionata come 1.2.3-beta.1.

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

__CAPGO_KEEP_0__ di riferimento

  • Comunica chiaramente la relazione tra le build. 1.2.3-beta.1 Comunica chiaramente la relazione tra le costruzioni. 1.2.3.
  • Consente di riutilizzare i numeri di versione all'interno di canali, riducendo la confusione.
  • Consente di riutilizzare i numeri di versione across canali, riducendo la confusione. 1.2.3, sai che 1.2.2 è la versione stabile precedente.

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.2, ecc.
  • QA canale: 1.2.3-qa.1, 1.2.3-qa.2, ecc.
  • Staging canale: 1.2.3-rc.1, 1.2.3-rc.2, ecc.
  • Production canale: 1.2.3, 1.2.4, ecc.

Utilizzando semver con identificatori di rilascio pre-annunciati è un approccio consigliato, ma non è strettamente necessario. 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.

Ripristinare una Live Update

Sezione intitolata “Ripristinare una Live Update”

Se si distribuisce una live update che introduce un bug o che necessita di essere annullata, è possibile ripristinare facilmente una versione precedente. Dalla sezione “Canali” del pannello di controllo:

  1. Selezionare il nome del canale da cui si desidera ripristinare
  2. Trovare la versione da cui si desidera ripristinare e cliccare sull'icona della corona Ripristina versione
  3. Confermare l'azione

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

Automazione delle distribuzioni

Sezione intitolata “Automazione delle distribuzioni”

Per flussi di lavoro più avanzati, è possibile automatizzare le distribuzioni di live update come parte del proprio pipeline CI/CD. Integrando Capgo nel proprio processo di build, è possibile caricare automaticamente nuovi bundle e assegnarli ai canali ogni volta che si pubblicano nuove versioni o si creano nuove release.

Consultare il Integrazione CI/CD docs to learn more about automating Capgo live updates.

Previsioni di PR con privilegi minimi

Previsioni di PR con privilegi minimi

Usare 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 predefiniti. La chiave rimane legata all'organizzazione proprietaria e all'app selezionata; semplicemente non ha alcun ruolo organizzativo. Ogni canale di anteprima non pubblico che crea riceve le proprie autorizzazioni di ciclo di vita automatiche, scoping per canale.

  1. Fare in modo che un amministratore dell'organizzazione crei una chiave API sicura limitata all'app di anteprima e selezioni Anteprima dell'appConsultare Chiavi API.
  2. Usare un canale unico e non pubblico come pr-123. Non passare --default, --self-assign, opzioni di rilascio, o --delete-linked-bundle-on-upload.
  3. Carica e promuovi il bundle PR in un comando, poi elimina il canale e il bundle di proprietà quando il 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 bundle e lo promuovi in un flusso. La pulizia è atomica e controllata dall'accesso: la chiave può eliminare solo un canale che ha creato e il suo bundle collegato e non condiviso. Non può cambiare, promuovere o eliminare un canale principale/di default, un canale di anteprima di un'altra chiave 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:

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

Un chiave di anteprima per App non può abilitare le anteprime da sola perché non dispone delle autorizzazioni di impostazioni dell'app. In GitHub azioni, eseguire i lavori di anteprima che contengono segreti. pull_request, non pull_request_target, e limitali ai PR con repository dello stesso tipo github.event.pull_request.head.repo.full_name == github.repository.

Distribuisci su un Dispositivo

Sezione intitolata “Deploying to a Device”

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 tuo canale desiderato
  3. Carica un build e assegna il canale a quel build
  4. Lancia l'app e attendi l'aggiornamento!

Per un walkthrough dettagliato, vedi il Aggiornamento in Tempo Reale guide. Buona fortuna con gli aggiornamenti!

Utilizzo avanzato dei canali: segmentazione degli utenti

Sezione intitolata “Utilizzo avanzato dei canali: segmentazione degli utenti”

Canali possono essere utilizzati per più di solo fasi di sviluppo. Sono uno strumento potente per la segmentazione degli utenti, consentendo funzionalità come:

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

Continua da qui dai canali

Sezione intitolata “Continua da Canali”

Se stai utilizzando Channels connettilo per pianificare la routing del canale e la distribuzione in fasi 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 nella Version Targeting Solution, e Capgo Pratiche per l'ambiente Migliore: Staging con un ID di App Mobile per il contesto pratico in Capgo Pratiche per l'ambiente Migliore: Staging con un ID di App Mobile.