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

Canali

Un canale di aggiornamenti in tempo reale punta a una specifica versione costruita 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 su quel canale controlla per gli aggiornamenti disponibili ogni volta che l'app viene avviata. Puoi modificare la versione a cui punta quel canale in qualsiasi momento e puoi anche tornare a versioni precedenti se necessario.

Come un dispositivo sceglie un canale (precedenza)

Sottosezione 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. Imposizione forzata del mapping del dispositivo (Dashboard) – Pianifica un ID dispositivo specifico su un canale. Utilizza per debug urgenti o test controllati con un singolo utente reale. Questo vince sempre. Capgo rimuove la mappatura 90 giorni dopo l'ultima scrittura di override. Vedi Console e override API 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. Riinstallando il binario non si cancella; eliminando l'override del dispositivo si cancella. La stessa conservazione dei 90 giorni si applica.
  3. Plugin setChannel() canale locale – Creato quando l'app chiama setChannel() e il backend verifica che il canale di destinazione consente l'assegnazione auto.
  1. Capacitor config 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 le versioni di test / costruzioni interne, in modo che i tester cadano su un canale di anteprima automaticamente. Le costruzioni di produzione lasciano spesso questo impostato su "nessuno".
  2. Canale predefinito di Cloud (percorso principale ~99% degli utenti) – Se segni un canale predefinito nel pannello di controllo, tutti gli utenti normali (nessun forzo, nessuna sovrascrittura del pannello di controllo/API, nessun canale locale del plugin, nessuna configurazione predefinita del canale) si attaccano qui. Cambialo per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai dei valori predefiniti specifici per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo si attacca al valore predefinito che corrisponde alla sua piattaforma. Lasciare il canale predefinito di Cloud non impostato è consentito; in quel caso il dispositivo deve corrispondere ai passaggi 1–4 per ricevere aggiornamenti.

Pratica consigliata:

  • Trovare un equilibrio tra i passaggi 1–4 e i canali di produzione. Quando si imposta un canale predefinito, gli utenti reali dovrebbero flusso in esso. Se non si imposta un canale predefinito, sia deliberato su come gli utenti si attaccano (di solito tramite defaultChannel in config o sovrascritture per dispositivo).
  • Configura solo defaultChannel in eseguibili che spedisci esplicitamente ai tester. Lasciarlo non impostato mantiene la logica di produzione centralizzata nel dashboard.
  • Usa setChannel() con parsimonia in produzione—principalmente per le prove di qualità o per 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 Cloud predefinita.

Console e API sovrascritture scadono dopo 90 giorni

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

Le mappature forzate e le sovrascritture del dashboard o del canale pubblico API sono memorizzate come assegnamenti per dispositivo in Capgo. Un lavoro di pulizia elimina quelle assegnazioni 90 giorni dopo l'ultima scrittura di overrideControllare l'aggiornamento non resettare quel timer. Solo scrivere l'override di nuovo (o cancellarlo da solo) cambia la data.

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

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

  • Impostare defaultChannel in capacitor.config.* (resiste alla reinstallazione; richiede un nuovo binario nativo per cambiarlo in seguito).
  • Chiamare setChannel() context: Appflow Migration Step2 setChannel() dal'applicazione. Dal plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 e in seguito, quella assegnazione è locale e non viene eliminata da questa pulizia. Reinstallando l'app, si cancella, quindi l'app deve chiamare di nuovo se si desidera ancora quel canale.

Canale Dispositivi tab del dispositivo e l'override UI elenca solo console e assegnamenti pubblici API. Non elenca ogni dispositivo sul canale e non elenca dispositivi locali setChannel() Assegnamenti.

Assegnamenti Capgo sul canale Dispositivi tab mostrando il popover di conservazione dell'override: gli override console scadono dopo 90 giorni
Attenzione di conservazione dell'override sul canale Dispositivi tab.

Comportamento del canale predefinito

Sottosezione intitolata “Comportamento del canale predefinito”

Impostare un default cloud è 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 un __CAPGO_KEEP_0__ nella configurazione riceveranno aggiornamenti. Quando scegli di segnalare i default, tieni presente queste regole: defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

  • – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico default; ogni dispositivo senza override si attaccherà qui. Comportamento predefinito del canale
  • Impostazioni specifiche della 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, i dispositivi 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 volete 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. Aprire il canale, poi

Gestisci in impostazioni dell'app Manage in App settings, che ti porta a Informazioni sull'app. Il default non è più un toggle sulla pagina del canale. Quando scambi un default, i nuovi dispositivi rispettano le nuove regole di routing immediatamente e i dispositivi esistenti seguono le normali regole di precedenza la prossima volta che si connettono.

Configurazione di un Canale

Sottosezione intitolata “Configurazione di un Canale”

Durante l'onboarding 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 sincronizzare i canali con le 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 di una maggiore diffusione
  • Staging - per test finali in un ambiente simile a quello di produzione
  • Production - per la versione dell'app che gli utenti finali ricevono dai negozi di app

Configurazione del canale nell'app

Sezione intitolata “Configurazione del canale nell'app”

Dopo aver creato i canali, è necessario 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, impostare optionalmente defaultChannel per le versioni di test (internale / 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.
    },
  },
};

Prossimo, 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 dei canali

Il titolo della sezione “Opzioni e strategie dei canali”

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

  • Canale predefinito: Opzionalmente segnala i canali o le piattaforme specifiche ai quali si attaccano i dispositivi nuovi. In questo caso, si trova nella console App Information (Gestisci le impostazioni dell'app da pagina del canale). Vedi “Comportamento del canale predefinito” per gli scenari di routing.
  • Filtro delle piattaforme: 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 dell'app nativa del dispositivo è più recente della versione del bundle del canale (ad esempio, dispositivo su 1.2.3 mentre il canale ha 1.2.2).
  • Consenti edizioni di sviluppo: Consentire gli aggiornamenti alle edizioni di sviluppo (utile per la prova). CLI: --dev / --no-dev.
  • Consenti edizioni di produzione: Consenti gli aggiornamenti alle edizioni di produzione (magazzino) lascia questo attivo per i canali che servono utenti reali. CLI: --prod / --no-prod.
  • Consenti dispositivi emulatori: Consenti gli aggiornamenti ai dispositivi emulatori/simulatore (utile per le prove). CLI: --emulator / --no-emulator.
  • Consenti dispositivi fisici: Consenti gli aggiornamenti ai telefoni e alle tablet reali. Lascia questo attivo per i canali di produzione. CLI: --device / --no-device.
  • Consenti l'assegnazione di dispositivi da parte dell'applicazione: Consente all'applicazione di passare a questo canale in esecuzione utilizzando setChannelSe disabilitato, setChannel fallirà per questo canale. CLI: --self-assign / --no-self-assign.
  • Pacco di aggiornamento: Scegli se i dispositivi scaricano un file zip completo, una delta dei file modificati o entrambi (all, zip, delta, zip_from_builtin, delta_from_builtinvedi Pacco di aggiornamento per il menu a discesa della console e quando ogni modalità è utile.

Rollout progressivo

Sezione intitolata “Rollout progressivo”

A un canale è possibile mantenere un bundle stabile mentre si espongono gradualmente un obiettivo di distribuzione separato a un gruppo di dispositivi adesivi. È possibile sospendere, riprendere, promuovere, tornare indietro e configurare una risposta di fallimento automatica senza cambiare il canale per tutti. Vedi Rollout progressivo per il modello di consegna, il flusso di lavoro del dashboard, API campi e CLI comandi.

Disabilita strategie di aggiornamento automatico

Sezione intitolata “Disabilita strategie di aggiornamento automatico”

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

  • maggiore: Blocca un bundle di destinazione con una versione maggiore di quella del baseline nativo 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 is blocked; 1.2.3 -> 1.2.4 is allowed.
  • patch: Modalità più rigorosa. Blocca qualsiasi modifica al numero maggiore, minore o di patch. Sono consentite solo le modifiche ai suffissi mentre MAJOR.MINOR.PATCH rimane identico. Esempi: 1.0.0-beta.1 -> 1.0.0-beta.2 is allowed; 1.0.0+build.1 -> 1.0.0+build.2 is allowed; 1.0.0 -> 1.0.1 is blocked.
  • metadata: Richiedi una versione di aggiornamento minima di metadati su ogni bundle. Configura tramite CLI usando --min-update-version o --auto-min-update-versionnessuna: Consentire tutti gli aggiornamenti secondo la compatibilità di semver
  • nessuna: Consentire tutti gli aggiornamenti secondo la compatibilità di semver nessuna: Consentire tutti gli aggiornamenti secondo la compatibilità di semver.

Queste strategie confrontano la versione del canale di destinazione con la versione nativa di base inviata come version_build, non la versione attualmente scaricata inviata come version_name.

Scopri i dettagli e gli esempi in Disable updates strategy a /docs/cli/commands/#disable-updates-strategy.

Esempio (CLI). Il canale deve già esistere (channel set non lo crea):

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


# 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 canale in modo programmatico durante l'esecuzione. Ciò è particolarmente utile per:

  • menu di QA/debug dove gli tester possono cambiare tra canali
  • Flussi di opt-in 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
});

Assegnare un Bundle a un Canale

Sottosezione intitolata “Assegnare un Bundle a un Canale”

Per distribuire un aggiornamento live, è 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 attiva per il Development canale. Gli app configurate per ascoltare quel canale riceveranno l'aggiornamento la prossima volta che ne faranno richiesta.

È anche possibile assegnare le build ai canali dalla sezione "Bundle" del Capgo dashboard. Cliccare sul menu icona accanto a una build e selezionare "Assegna al canale" per scegliere il canale per quella build.

Versionamento dei bundle e canali

Sottosezione intitolata "Versionamento dei bundle e canali"

È 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 bundle, consigliamo di utilizzare la versione semantica con il Capgo's Tester Semver e gli identificatori di pre-uscita per le build specifiche del canale. Ad esempio, una versione beta potrebbe essere versionata come In CI, se la versione locale era già caricata, utilizzare 1.2.3-beta.1.

(facoltativamente) npx @capgo/cli@latest bundle upload --auto-bump , o major, minor, patch/fix, metadata) in modo che il __CAPGO_KEEP_0__ aumenti dal bundle del canale collegato fino a trovare un nome libero. Con ai) so the CLI bumps from the channel’s linked bundle until a free name is found. With ai, Workers AI determina il livello dalla manifest locale rispetto al delta precedente (ricade su patch con nessuna versione precedente Capgo). Non puoi combinarlo con --bundle. Vedi e la __CAPGO_KEEP_0__ reference CLI reference.

Comunica chiaramente la relazione tra le build.

  • è ovviamente una versione pre-release di 1.2.3-beta.1 Consente di riutilizzare i numeri di versione across canali, riducendo la confusione. 1.2.3.
  • Abilita percorsi di rollback chiari. Se hai bisogno di tornare indietro da
  • , sai 1.2.3CI/CD Integration 1.2.2 è la versione di rilascio 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.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.

Utilizzando semver con identificatori di rilascio pre-annunciati è 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.

Ripristino di una Aggiornamento in Tempo Reale

Sottosezione intitolata “Ripristino di una Aggiornamento in Tempo Reale”

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

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

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

Automazione delle Distribuzioni

Sottosezione intitolata “Automazione delle Distribuzioni”

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

Esegui una visita ai Eseguimento CI/CD docs to learn more about automating Capgo live updates.

Documentazione per imparare di più su l'automazione delle aggiornamenti live.

Previsioni di PR con minori privilegi

Sottosezione intitolata “Previsioni di PR con minori privilegi” Usa un API key when CI needs one temporary channel per pull request but must not manage existing main/default channels. The key remains bound to the owning organization and selected app; it simply has no organization-wide role. Each non-public preview channel it creates receives its own automatic, channel-scoped lifecycle permission.

  1. Chiave API 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 a livello di organizzazione. Ogni canale di anteprima non pubblico che crea riceve le proprie autorizzazioni di ciclo di vita automatiche, scritte a livello di canale. Hai un amministratore dell'organizzazione che crea una chiave __CAPGO_KEEP_0__ sicura limitata all'app di anteprima e selezionaAnteprima dell'app Vedi le chiavi API.
  2. Usa un canale unico, non pubblico, come pr-123Non passare --default, --self-assign, opzioni di rilascio, o --delete-linked-bundle-on-upload.
  3. Carica e promuovi il bundle PR in un comando, quindi 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 promuove 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ò modificare, 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

Una chiave di anteprima dell'app non può abilitare le anteprime da sola perché non ha la permessione di impostazioni dell'app. In GitHub Actions, esegui i lavori di anteprima che portano segreti su pull_request, non pull_request_target, e limitarli ai PR con repository identico con github.event.pull_request.head.repo.full_name == github.repository.

Deployare su un Dispositivo

Sottosezione intitolata “Deployare su un Dispositivo”

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

  1. Installare 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 Deployare Aggiornamenti Live guide. Buona fortuna con gli aggiornamenti!

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

  • Bandiere di feature per diversi livelli di utenti
  • Test A/B
  • Rilascio graduale di feature
  • Programmi di test beta

Scopri come implementare questi casi d'uso avanzati nella nostra guida: Come segmentare gli utenti in base al piano e ai canali per le bandiere di feature e i test A/B.

Continua da qui dai canali

Sezione intitolata “Continua da qui dai canali”

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