Channel Surfing per Capgo: come cambiare i canali di update a runtime

Avresti mai voluto pubblicare una modifica direttamente a un utente specifico per una sua immediata revisione e feedback, senza chiedergli di scaricare e installare un nuovo build da TestFlight o Google Play?

Ho avuto clienti che chiedevano miglioramenti che sono riuscito a implementare rapidamente, ma far arrivare i risultati nelle loro mani per la validazione significava pubblicare un aggiornamento a tutti gli utenti (rischioso per una modifica sperimentale) o creare un build one-off specificamente per il cliente (un fastidio per entrambi).

Ciò che mancava era la flessibilità. Gli sviluppatori volevano poter servire aggiornamenti diversi a diversi gruppi di utenti, come stakeholder non tecnici, QA o l'intera base utenti quando appropriato.

Non c'era modo per un build di produzione di passare a una versione in lavorazione, raccogliere feedback e poi tornare alla produzione.

È questo che cambiare canale rende possibile. Un'app installata sul dispositivo di un utente può cambiare canale di aggiornamento a runtime, trasformando un'app di produzione in uno spazio flessibile per revisione e iterazione anziché in un endpoint fisso. Questo è particolarmente utile per stakeholder non tecnici che lavorano con app di produzione, permettendo loro di testare modifiche e dare feedback direttamente nell'app che hanno già installato.

Comprendere i canali di aggiornamento

I canali di aggiornamento sono il modo in cui Capgo indirizza gli aggiornamenti a build specifici. Ogni build è associato a un canale, e quel canale determina quali aggiornamenti riceverà.

Ad esempio, puoi pubblicare aggiornamenti su un preview channel senza influenzare gli utenti su production. In passato, cambiare channel richiedeva di installare una build nativa diversa o di modificare manualmente le assegnazioni dei dispositivi tramite la dashboard.

I channel in Capgo ti permettono di:

Assegna funzionalità diverse a gruppi specifici di utenti
Esegui A/B test assegnando gli utenti a canali differenti
Rilascia nuove feature in modo graduale
Crea programmi di beta testing
Debuggare problemi in produzione con singoli utenti

Se non conosci i channel di aggiornamento, la documentazione dei channel di Capgo li tratta più nel dettaglio.

Cos'è il Channel Surfing?

Il channel surfing consente a un'app installata di prelevare da diversi flussi di aggiornamento senza reinstallarla. Un'app installata può cambiare canale di aggiornamento a runtime e continuerà a ricevere aggiornamenti dal nuovo canale selezionato finché non viene disinstallata o cambiata a un altro canale.

In pratica, questo significa che un product owner o un QA può passare a una production build, ad esempio, a un preview canale, per provare le ultime modifiche. Una volta terminati i test, torna a production di nuovo. Non è necessaria una reinstallazione o una build di anteprima separata.

Sotto il cofano, il channel surfing funziona permettendo all'app di indicare al client di aggiornamenti quale canale utilizzare. Questa scelta può essere modificata a runtime e resta in vigore finché non viene rimossa o sostituita.

Come implementare il Channel Surfing

Prima di poter provare il channel surfing, il tuo progetto deve essere configurato con Capgo Live Updates. Per configurarlo, segui la quickstart guide di Capgo.

L'unica configurazione richiesta per il channel surfing è abilitare "Allow devices to self associate" su ogni canale a cui si desidera passare nel dashboard di Capgo. Nessuna modifica a code o alla configurazione è necessaria oltre a questo.

Alla base, il cambio canale è guidato da una singola chiamata API:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setChannel({ channel: 'your-channel' });

Questo imposta il canale utilizzato quando si interroga Capgo per gli aggiornamenti. Scopri di più su setChannel API.

Cambio canale istantaneo (v5.34.0+)

A partire dalle versioni del plugin 5.34.0, 6.34.0, 7.34.0 o 8.0.0 (in base alla tua major version), setChannel() funziona in modo diverso e molto più veloce:

Validazione backend (sola lettura): viene inviata una richiesta al backend Capgo per verificare che il canale sia consentito
Aggiornamento dello storage locale: se la verifica passa, il canale viene salvato nella memoria locale del dispositivo
Effetto immediato: Il prossimo controllo aggiornamenti usa subito il nuovo channel

In precedenza, setChannel() l'override del channel veniva salvato nel database del backend (come per le modifiche da Dashboard o API). I dispositivi dovevano attendere la replica del backend (fino a 2 minuti) prima che il nuovo channel fosse riconosciuto. Il nuovo comportamento legge solo dal backend (per la validazione) e salva in locale, rendendo il cambio di channel istantaneo.

Flusso completo di cambio channel

Per una migliore UX, di solito vorrai fare più che cambiare semplicemente il channel e attendere il prossimo riavvio dell'app. Un approccio comune è controllare subito gli aggiornamenti, scaricarli se disponibili e ricaricare l'app, così l'utente arriva direttamente sull'aggiornamento del channel selezionato.

Un flusso tipico è questo:

Cambia il channel (setChannel)
Controlla gli aggiornamenti (getLatest)
Recupera e applica l'update (download, set oppure next)
Ricarica l'app se necessario (reload)

Ecco un esempio completo:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

async function switchChannel(selectedChannel: string) {
  try {
    // 1. Set the updates channel (with optional auto-update trigger)
    await CapacitorUpdater.setChannel({
      channel: selectedChannel,
      triggerAutoUpdate: true // Immediately check for updates
    });

    console.log(`Switched to channel: ${selectedChannel}`);

    // If you want more control, handle the update manually:
    // const latest = await CapacitorUpdater.getLatest();
    // if (latest.url) {
    //   const bundle = await CapacitorUpdater.download({
    //     url: latest.url,
    //     version: latest.version
    //   });
    //   await CapacitorUpdater.set({ id: bundle.id });
    // }

  } catch (error) {
    console.error('Failed to switch channel:', error);
  }
}

// Switch to the beta channel
switchChannel('beta');

Come strutturare questo flusso sta a te. Puoi suddividere questi passaggi in più interazioni o eseguirli tutti insieme. Indipendentemente da come strutturi il flusso, assicurati di gestire i casi di errore. Problemi di rete o un canale non valido possono impedire l'applicazione di un aggiornamento.

L'unico requisito: abilita l'auto-assegnazione

Questa è l'unica cosa che devi fare per abilitare il cambio di canale. Prima che la tua app possa passare a un canale usando setChannel(), devi abilitare l'auto-assegnazione per quel canale nella dashboard di Capgo:

Vai a Canali sezione nella tua dashboard di Capgo
Clicca sul nome del canale che vuoi gestire
Abilita “Consenti ai dispositivi di auto-associarsi”
Salva le modifiche

Abilita l'auto-assegnazione nelle impostazioni del canale

Tutto qui. Non serve modificare la configurazione dell'app. Nessuna defaultChannel impostazione richiesta. Basta abilitare l'auto-assegnazione sui canali a cui vuoi che gli utenti possano passare.

Se questa impostazione è disabilitata, ogni tentativo di chiamare setChannel() con questo canale fallirà e l'evento channelPrivate verrà emesso.

Elenco dei canali disponibili

Puoi recuperare l'elenco dei canali disponibili per l'auto-assegnazione:

const { channels } = await CapacitorUpdater.listChannels();

console.log('Available channels:', channels.map(c => c.name));
// Use this to build a channel selector UI

Restituisce solo i canali con l'auto-assegnazione abilitata.

Ottieni il canale corrente

Verifica a quale canale è attualmente assegnato il dispositivo:

const { channel } = await CapacitorUpdater.getChannel();

console.log('Current channel:', channel);

Ripristino del canale predefinito

Per rimuovere l'override del canale e tornare al predefinito:

await CapacitorUpdater.unsetChannel({});

Questo scollega il dispositivo da qualsiasi canale specificamente assegnato, facendolo tornare al defaultChannel nella tua configurazione o al predefinito cloud.

Come testare il Channel Surfing

Per vedere il channel surfing in azione, ti servirà una release build - la @capgo/capacitor-updater API è progettata per le release build. Nelle debug build, l'app carica tipicamente il JavaScript da un server di sviluppo, bypassando il flusso di aggiornamento normale.

Prerequisiti

L'unico requisito per il channel surfing è abilitare “Consenti ai dispositivi di auto-associarsi” su ogni canale verso cui vuoi consentire il passaggio. Non sono necessari cambiamenti di configurazione nella tua app.

Creare una build di test

Compila la tua app come di consueto:

bun run build && npx cap sync

Poi crea i tuoi Native Build usando Xcode o Android Studio, oppure usa la tua pipeline CI/CD. L'app si avvierà sul canale impostato come default cloud nella dashboard di Capgo.

Pubblicare update su canali diversi

Una volta installata l'app, pubblica update su canali diversi:

# Publish to preview channel
npx @capgo/cli@latest bundle upload --channel preview

# Publish to production channel
npx @capgo/cli@latest bundle upload --channel production

Da lì, vai alla UI di channel surfing nell'app e attiva il cambio di canale. L'app dovrebbe recuperare l'update dal canale selezionato e ricaricarsi con il nuovo update.

Creare una UI per il Channel Switcher

Il channel surfing è di solito una funzione da esporre a un set limitato di utenti, non a tutti quelli che usano l'app. Ad esempio, potresti avere un pulsante disponibile solo per i dipendenti autenticati che passa l'app al canale preview.

Ecco un esempio di componente React per un channel switcher:

import { useState, useEffect } from 'react';
import { CapacitorUpdater } from '@capgo/capacitor-updater';

export function ChannelSwitcher() {
  const [currentChannel, setCurrentChannel] = useState<string>('');
  const [availableChannels, setAvailableChannels] = useState<string[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    loadChannelInfo();
  }, []);

  async function loadChannelInfo() {
    const { channel } = await CapacitorUpdater.getChannel();
    setCurrentChannel(channel || 'default');

    const { channels } = await CapacitorUpdater.listChannels();
    setAvailableChannels(channels.map(c => c.name));
  }

  async function handleChannelSwitch(channel: string) {
    setIsLoading(true);
    try {
      await CapacitorUpdater.setChannel({
        channel,
        triggerAutoUpdate: true
      });
      setCurrentChannel(channel);
      // App will update in background or on next restart
    } catch (error) {
      console.error('Failed to switch channel:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div>
      <p>Current channel: {currentChannel}</p>
      <div>
        {availableChannels.map(channel => (
          <button
            key={channel}
            onClick={() => handleChannelSwitch(channel)}
            disabled={isLoading || channel === currentChannel}
          >
            Switch to {channel}
          </button>
        ))}
      </div>
    </div>
  );
}

Criticità degli OTA update

Nessuna di queste è specifica del channel surfing, ma tendono a emergere rapidamente non appena inizi a cambiare canale a runtime.

Mismatch della versione runtime

Gli update in Capgo sono legati alle versioni native dell'app. Se la versione nativa di un update non corrisponde a quella dell'app installata, l'update non verrà scaricato né applicato. Durante il channel surfing, questo si manifesta spesso con l'app che cambia canale senza applicare l'update, anche se su quel canale ce n'è uno.

Solitamente significa che l'update è stato pubblicato da una versione nativa diversa dell'app. Assicurati che il bundle del canale sia compatibile con la versione nativa installata sul dispositivo.

Rimozione o annullamento degli aggiornamenti

Se un'app ha già scaricato un aggiornamento per un canale, eliminarlo dalla dashboard di Capgo non lo rimuove dai dispositivi che lo hanno già installato. L'eliminazione blocca solo i download futuri.

Il modo più affidabile per annullare un aggiornamento errato è pubblicare un aggiornamento noto come stabile sullo stesso canale. Questo crea un nuovo aggiornamento in cima alla cronologia del canale, che i client tratteranno come versione più recente e applicheranno al posto del precedente.

Capgo offre anche un meccanismo di rollback che può istruire i client a riapplicare un aggiornamento stabile precedente o a tornare all'aggiornamento incorporato nel build.

Considerazioni sulla migrazione dei dati

Il cambio di canale modifica il bundle JavaScript eseguito dall'app. Se l'app dipende da migrazioni o strutture dati non compatibili tra i canali, il passaggio continuo tra essi potrebbe causare problemi.

Ad esempio, se un aggiornamento beta applica una migrazione al database, la versione in produzione potrebbe non riconoscere il nuovo schema. Gli sviluppatori devono assicurarsi che sia sicuro passare da un aggiornamento all'altro, o limitare il passaggio a una sola direzione quando necessario.

Perché il channel surfing migliora l'iterazione mobile

Il channel surfing è particolarmente utile quando devi rivedere rapidamente le modifiche in un ambiente di produzione.

Validazione rapida

Immagina un bug fix urgente che deve essere validato prima del rollout globale. Con il channel surfing, la modifica può essere isolata a un piccolo gruppo di utenti designati che possono testarla prima che raggiunga la produzione.

Revisione degli stakeholder

Un product owner o un QA può cambiare il canale di aggiornamento della build di produzione installata, verificare il fix o la feature e poi tornare al canale originale una volta finito.

Testing semplificato

Questo facilita il coinvolgimento degli stakeholder non tecnici nella revisione e nel processo decisionale, mantenendo il workflow fluido. Una singola build di produzione diventa uno strumento flessibile per test, feedback e validazione.

Casi d'uso

Test QA: Il team QA passa tra i rami delle funzionalità
Programmi beta: Gli utenti si iscrivono al canale beta per l'accesso anticipato
Revisione degli stakeholder: I product owner anteprima le modifiche prima del rilascio
A/B testing: Assegna utenti a canali diversi per esperimenti
Debug: Passa un utente specifico a un canale di debug per diagnosticare problemi

Confronto: Metodi di cambio canale

Metodo	Tempo di effetto	Dove viene salvato	Caso d'uso
`setChannel()` dal plugin	Istantaneo	Solo dispositivo (locale)	Cambio canale in-app avviato dall'utente
Override dispositivo dalla dashboard	Fino a 2 min	Database backend	Modifiche admin per dispositivi specifici
Assegnazione canale API	Fino a 2 min	Database backend	Integrazioni backend automatizzate

Per la migliore UX quando crei interfacce per il cambio di canale, usa sempre il setChannel() metodo.

Best practice

Limita l'accesso: Il cambio canale è solitamente per uso interno: non esporlo a tutti gli utenti
Gestisci gli errori: Gestisci sempre gli errori in modo elegante quando cambi canale
Valida la compatibilità: Assicurati che gli aggiornamenti sui diversi canali siano compatibili con la versione nativa installata
Documenta i canali: Mantieni una documentazione chiara su a cosa serve ogni canale
Monitora l'utilizzo: Tieni traccia di quali dispositivi sono su quali canali per il debug

Risorse

Conclusione

Il channel surfing trasforma il modo in cui iteri sulla tua app Capacitor. Invece di considerare i build di produzione come punti finali fissi, diventano strumenti flessibili per test, validazione e iterazione rapida.

Con il cambio di canale istantaneo introdotto nelle versioni recenti del plugin, l'esperienza è ora senza interruzioni: gli utenti possono cambiare canale e ricevere immediatamente gli aggiornamenti dal nuovo canale, senza tempi di attesa.

Che tu stia validando le correzioni dei bug con gli stakeholder, gestendo programmi beta o debuggando problemi con utenti specifici, il channel surfing ti offre la flessibilità di consegnare l'aggiornamento giusto all'utente giusto nel momento giusto.

Continua con Channel Surfing per Capgo: come cambiare i canali di aggiornamento a runtime

Se stai usando Channel Surfing per Capgo: come cambiare i canali di update a runtime per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow di prodotto nella Soluzione Beta Testing, e Soluzione Version Targeting per il workflow di prodotto nella Soluzione Version Targeting.