Saltare al contenuto

Canali

Un canale di aggiornamento in tempo reale punta a una specifica costruzione di pacchetto JS del tuo'applicazione 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'applicazione, qualsiasi binario nativo configurato su quel canale controlla per gli aggiornamenti disponibili ogni volta che l'applicazione viene avviata. Puoi modificare la costruzione a cui punta quel canale in qualsiasi momento e puoi anche tornare a costruzioni precedenti 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. Impegno forzato 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 dopo 90 giorni dall'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. Ristallando il binario non si cancella; eliminando l'override del dispositivo si cancella. La stessa conservazione di 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 costruzioni di TestFlight / interne, in modo che i tester atterrino su un canale di anteprima automaticamente. Le costruzioni di produzione lasciano spesso questo impostato su null.
  2. Canale predefinito Cloud (percorso principale ~99% degli utenti) – Se segni un canale predefinito nel pannello di controllo, tutti gli utenti normali (nessun forzamento, nessuna sovrascrittura del pannello di controllo/API, nessun plugin locale canale, nessuna configurazione defaultChannel) si attaccano qui. Modificare per distribuire o ritirare immediatamente—nessun nuovo binario. Se hai dei default specifici per piattaforma (ad esempio, uno solo per iOS, uno solo per Android, uno solo per Electron), ogni dispositivo atterra sul default 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 un modo per trattare 1–4 come livelli di eccezione/test; quando imposti un canale predefinito, gli utenti reali dovrebbero flusso in esso. Se non lo imposti, essere deliberato su come gli utenti si attaccano (di solito tramite defaultChannel configurare in config o sovrascrivere per dispositivo).
  • Sono abilitati solo la configurazione defaultChannel configurare in binari che spedite esplicitamente ai tester. Lasciare in bianco mantiene la logica di produzione centralizzata nel dashboard.
  • Usare setChannel() usare 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 > Dashboard/API Override > Plugin setChannel() canale locale > Config defaultChannel > Impostazione Cloud predefinita.

I mapping obbligatori e le sovrascritture del dashboard o del canale pubblico API sono memorizzati come assegnamenti per dispositivo in Capgo. Un lavoro di pulizia elimina quegli assegnamenti 90 giorni dopo l'ultima scrittura di overrideLa verifica di un aggiornamento non resettare quel clock. Solo la scrittura dell'override nuovamente (o cancellandolo 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:

  • Imposta defaultChannel in capacitor.config.* (resiste alla reinstallazione; richiede un nuovo binario nativo per cambiare in seguito).
  • Chiamare setChannel() contexto: frammento di testo HTML da una stringa Capgo UI più lunga (chiave genitoriale `appflow_migration_step2`). Pagina/area: Appflow comparison / migrazione marketing copy. Ruolo: copia del sito web frase. Visualizzato in: pagina ionic-appflow.astro. Preservare i termini del prodotto/marca e dei sviluppatori esattamente. Chiave del messaggio `appflow_migration_step2` (Appflow Migration Step2). setChannel() dal'app. 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

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

Capgo canale Dispositivi tab mostrando la popover di retention Override: le sovrapposizioni console scadono dopo 90 giorni
Attenzione di scadenza delle sovrapposizioni sul canale Dispositivi tab.

Impostare un default cloud è facoltativo, ma di solito funge da percorso di default per i nuovi dispositivi. Senza uno, solo i dispositivi che corrispondono alle mappature forzate, alle sovrapposizioni o a una defaultChannel Capacitor configurazione riceveranno aggiornamenti. Quando scegli di segnalare i default, tieni presente queste regole:

  • Default unico (più comune) – Se un canale ha iOS, Android e Electron abilitati, diventa l'unico default; ogni dispositivo senza sovrapposizioni si attaccherà qui.
  • Predefiniti specifici 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, gli Android vanno al default Android, e le applicazioni Electron vanno al default Electron.

Ricordate che il predefinito cloud e defaultChannel entrambi occupano lo stesso livello di decisione. Se impostate un predefinito 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 predefinito cloud è diverso. defaultChannel Potete modificare i predefiniti in qualsiasi momento nel pannello di controllo. Aprire il canale, poi

Gestisci in Impostazioni dell'app Manage in App settingsquale 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 impostazioni di routing immediatamente e i dispositivi esistenti seguono le regole di precedenza normali la prossima volta che si connettono.

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

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 (interno / QA). Per le costruzioni 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.
},
},
};

Costruisci successivamente la tua 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 configurati precedentemente.

Il canale 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 app web, il CLI, o il Public API.

  • Canale predefinito: Opzionalmente segnala il canale o i canali specifici per piattaforma che i nuovi dispositivi si collegano. In questo caso vive nella console 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, Androido dispositivi per canale. Electron 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 costruzioni di sviluppo: Consentire gli aggiornamenti alle costruzioni di sviluppo (utili per la prova). __CAPGO_KEEP_0__:
  • Allow development builds: Permit updates to development builds (useful for testing). CLI: --dev / --no-dev.
  • Consenti costruzioni di produzione: Consentire aggiornamenti alle costruzioni di produzione (archivio) lasciare questo attivo per i canali che servono utenti reali. CLI: --prod / --no-prod.
  • Consenti dispositivi emulatori: Consentire aggiornamenti ai dispositivi emulatori/simulatore (utile per le prove). CLI: --emulator / --no-emulator.
  • Consenti dispositivi fisici: Consentire aggiornamenti a telefoni e tablet reali. Lasciare questo attivo per i canali di produzione. CLI: --device / --no-device.
  • Consenti l'assegnazione di dispositivi da parte dell'applicazione: L'applicazione può passare a questo canale in esecuzione utilizzando setChannelSe disabilitato, setChannel fallirà per questo canale. CLI: --self-assign / --no-self-assign.
  • Pacchetto di aggiornamento: Scegliere se i dispositivi scaricano un file zip completo, una delta dei file modificati o entrambi (all, zip, delta, zip_from_builtin, delta_from_builtinvedere Pacchetto di aggiornamento per il menu a discesa della console e quando ogni modalità è utile.

A un canale è possibile mantenere un pacchetto stabile mentre si espongono gradualmente un obiettivo di distribuzione separato a un gruppo di dispositivi fedeli. Vedi for the delivery model, dashboard workflow, API fields, and CLI commands.

per il modello di consegna, il flusso di lavoro del pannello di controllo, __CAPGO_KEEP_0__ campi e __CAPGO_KEEP_1__ comandi.

Disabilita strategie di aggiornamento automatico

Sottosezione intitolata “Disabilita strategie di aggiornamento automatico”

  • Utilizza questo per limitare i tipi di aggiornamenti che il canale consegnerà automaticamente. Opzioni:version_buildmaggiore: Blocca un pacchetto di destinazione con una versione maggiore rispetto alla versione nativa del dispositivo di base ( 1.2.3 -> 2.0.0 esempio: 1.2.3 -> 1.9.0 è bloccato;
  • è consentito. version_buildminore: Blocca un pacchetto di destinazione con una versione maggiore o minore rispetto a quella di base (esempio: 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 di versione 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 nel metadati di ogni bundle. Configura tramite CLI usando --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.
  • nessuna: Consentire tutti gli aggiornamenti secondo la compatibilità di semver o.

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

Scopri di più dettagli e esempi nella strategia di disabilitazione degli aggiornamenti in /docs/cli/comandi/#disabilita-aggiornamenti.

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

La setChannel() metodo consente al tuo app di passare dinamicamente tra i canali durante l'esecuzione. Ciò è particolarmente utile per:

  • menu di debug/QA dove i tester possono passare tra i 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
});

Per distribuire un aggiornamento live, è necessario caricare un nuovo build del bundle JS e assegnarlo a un canale. Ciò può essere fatto in un'unica operazione 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. Tutti gli app configurate per ascoltare quel canale riceveranno l'aggiornamento la prossima volta che ne cercheranno uno.

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

È 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 gli identificatori di pre-uscita per le build 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, metadata, o ai) in modo che il CLI aumenti dal pacchetto collegato del canale fino a trovare un nome libero. Con 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 Integrazione CI/CD contexto: Pagina/Area: Capgo Builder / prodotto di build nativa cloud. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave di messaggio `native_build_feature_ci_cd` (Feature di costruzione nativa Ci Cd). CLI reference.

riferimento __CAPGO_KEEP_0__

  • Questa approccio ha diversi benefici: 1.2.3-beta.1 Comunica chiaramente la relazione tra le costruzioni. 1.2.3.
  • è ovviamente una versione pre-release di
  • Consente di riutilizzare i numeri di versione across canali, riducendo la confusione. 1.2.3Abilita percorsi di rollback chiari. Se hai bisogno di tornare indietro da , sai 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.

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 sul nome del canale che desideri ripristinare
  2. Cerca la build che desideri ripristinare e clicca sull'icona della corona Ripristina build
  3. Conferma l'azione

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

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 certe branch o crei nuove release.

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

Documenti per imparare di più sulle automatizzazioni delle __CAPGO_KEEP_0__ aggiornamenti in tempo reale.

Previsioni PR con privilegi minimi

Sottosezione intitolata “Previsioni PR con privilegi minimi” 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. 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 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 con un comando, quindi elimina il canale e il bundle di proprietà quando il 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 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:

Fermata di sistema
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_requestnon pull_request_target, e limitarli ai PR con repository identico 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. 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 per piano e canali per le bandiere di feature e i test A/B.

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