Targeting delle versioni

Questa guida spiega come distribuire automaticamente l'ultimo bundle compatibile agli utenti in base alla versione della loro app nativa, simile all'approccio di Ionic AppFlow. Ciò semplifica la gestione degli aggiornamenti e accelera i rollout, evitando problemi di compatibilità.

Stai migrando da Ionic AppFlow?

Se arrivi da Ionic AppFlow, questa guida è particolarmente importante per te. AppFlow abbinava automaticamente gli aggiornamenti alle versioni native, mentre Capgo offre la stessa funzionalità con ancora più controllo e flessibilità. Consulta la Guida alla migrazione da AppFlow per istruzioni di migrazione passo dopo passo.

Panoramica

Il sistema di version targeting di Capgo ti permette di:

• Distribuire automaticamente update compatibili agli utenti in base alla versione nativa dell'app
• Evitare che le breaking changes raggiungano versioni dell'app incompatibili
• Gestire più versioni dell'app contemporaneamente senza logiche complesse
• Distribuisci gli update senza attriti a segmenti specifici di utenti

Perché il Version Targeting è fondamentale (specialmente per gli utenti AppFlow)

Se hai familiarità con Ionic AppFlow, sai quanto sia critico garantire che gli utenti ricevano solo update compatibili. AppFlow associava automaticamente i bundle live update alle versioni native dell'app, evitando che JavaScript incompatibili venissero inviati a vecchi code nativi.

Capgo offre le stesse garanzie di sicurezza, con funzionalità aggiuntive:

• Controllo più granulare sul version matching
• Strategie multiple (canali, semver, vincoli nativi)
• Maggiore visibilità sulla distribuzione delle versioni
• API e CLI si gestiscono insieme alla dashboard

Questo approccio è particolarmente utile quando:

• Hai utenti su diverse versioni principali della tua app (es. v1.x, v2.x, v3.x)
• Devi mantenere la backward compatibility durante il rilascio di breaking changes
• Vuoi evitare che bundle più recenti rompano vecchi code nativi
• Stai migrando gli utenti gradualmente da una versione all'altra
• Stai migrando da AppFlow e vuoi mantenere lo stesso livello di sicurezza degli update

Come funziona

Capgo usa un approccio multi-livello per abbinare gli utenti agli update compatibili:

1. Vincoli di versione native: Impedisce la consegna dei bundle a versioni native incompatibili
2. Routing basato sui Channel: Instrada versioni diverse dell'app verso canali di update diversi
3. Controlli del Semantic Versioning: Blocca automaticamente gli update tra versioni major, minor o patch
4. Override a livello di dispositivo: Indirizza dispositivi specifici o gruppi di utenti

Flusso di matching delle versioni

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check local plugin channel}
    D -->|setChannel value| E[Use local setChannel channel]
    D -->|No local channel| F{Check defaultChannel in App}
    F -->|Has defaultChannel| G[Use App's defaultChannel]
    F -->|No defaultChannel| H[Use Cloud Default Channel]
    C --> I{Check Version Constraints}
    E --> I
    G --> I
    H --> I
    I -->|Compatible| J[Deliver Update]
    I -->|Incompatible| K[Skip Update]

Strategia 1: Routing delle versioni basato sui channel

Questo è l' approccio consigliato per gestire breaking changes e aggiornamenti di versione major. È simile al modello di distribuzione di AppFlow.

Scenario di esempio

• App v1.x (100.000 utenti) → production canale
• App v2.x (50.000 utenti con breaking changes) → v2 canale
• App v3.x (10.000 utenti beta) → v3 canale

Implementazione

Passaggio 1: Configura i canali per ogni versione major

// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production', // or omit for default
    }
  }
};

export default config;

// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // Routes v2 users automatically
    }
  }
};

// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

Passaggio 2: Crea i canali

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

Passaggio 3: Carica i bundle per versione

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

Routing automatico

Quando gli utenti aprono l'app, si connettono automaticamente al canale designato in base alla defaultChannel nel bundle dell'app installata. Nessuna modifica al code JavaScript richiesta!

Vantaggi

• Zero modifiche al code - Il routing dei channel è automatico
• Separazione netta - Ogni versione ha la sua pipeline di update
• Targeting flessibile - Spingi update a gruppi di versioni specifici
• Rollout sicuri - I breaking change non raggiungono versioni incompatibili

Strategia 2: Controlli sul Semantic Versioning

Usa i controlli integrati di Capgo per il semantic versioning per evitare update tra versioni diverse.

Disabilita l'auto-update tra le major version

# Create a channel that blocks major version updates
npx @capgo/cli channel add stable
npx @capgo/cli channel set stable --disable-auto-update major

Questa configurazione significa:

• Gli utenti con versione app 1.2.3 riceveranno aggiornamenti fino a 1.9.9
• Gli utenti NON riceveranno la versione 2.0.0 automaticamente
• Evita che breaking changes raggiungano vecchi code nativi
• Il confronto utilizza il baseline nativo inviato come version_build

Opzioni di controllo granulare

# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch

# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Richiesto Semantic Versioning

Questa strategia funziona solo se segui il versionamento semantico (semver) per le versioni della tua app. Assicurati che i numeri di versione seguano il MAJOR.MINOR.PATCH formato.

Strategia 3: Vincoli sulla native version

Specifica una versione minima dell'app native (min_update_version) su ogni bundle, così Capgo lo invierà solo ai dispositivi con un binario native sufficientemente aggiornato.

Questo utilizza la strategia metadati del canale (--disable-auto-update metadata) unita a --min-update-version o --auto-min-update-version al momento dell'upload. Non esiste un --native-version flag CLI.

Abilita il targeting dei metadati sul channel

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Imposta una native version minima all'upload

Quando carichi un bundle, specifica la versione nativa più bassa che può riceverlo:

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "2.0.0"

Oppure lascia che Capgo fissi il minimo dalla compatibilità del pacchetto nativo:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

Come funziona

Con la strategia basata sui metadati, i dispositivi con baseline nativa ("version_build) inferiore alla versione del bundle min_update_version saltano l'aggiornamento. Solo i dispositivi con quella versione o superiore lo ricevono. Vedi Compatibilità per --auto-min-update-version i dettagli.

Casi d'uso

1. Nuovo plugin nativo richiesto

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Modifiche breaking al API nativo

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "3.0.0"

3. Migrazione Graduale

   # one-time: enable metadata gating on beta
   npx @capgo/cli@latest channel set beta --disable-auto-update metadata
   
   # Test bundle only on latest native version
   npx @capgo/cli@latest bundle upload \
     --channel beta \
     --min-update-version "2.5.0"

Strategia 4: Prevenzione Auto-Downgrade

Impedisci agli utenti di ricevere bundle più vecchi della loro versione native attuale.

Abilita nelle Channel Settings

Nel dashboard di Capgo:

1. Vai su Canali → Seleziona il tuo canale
2. Abilita “Disabilita il downgrade automatico in modalità native”
3. Salva modifiche

O tramite CLI:

npx @capgo/cli@latest channel set production --no-downgrade

Esempio

• Dispositivo dell’utente: versione native 1.2.5
• Bundle del canale: versione 1.2.3
• Risultato: L'aggiornamento è bloccato (sarebbe un downgrade)

È utile quando:

• Gli utenti hanno installato manualmente una versione più recente dall'app store
• Devi garantire che gli utenti abbiano sempre le ultime patch di sicurezza
• Vuoi prevenire bug di regressione

Strategia 5: Targeting a livello di dispositivo

Sovrascrivi l'assegnazione del canale per dispositivi specifici o gruppi di utenti.

Forza una versione specifica per i test

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

Override dei dispositivi nella Dashboard

Nella dashboard di Capgo:

1. Vai su Dispositivi → Trova il dispositivo
2. Clicca su Imposta Channel o Imposta Version
3. Override con channel o versione bundle specifica
4. Il dispositivo riceverà gli update dalla sorgente indicata

Test degli update

Usa gli override del dispositivo per testare gli update sul tuo dispositivo prima di rilasciarli a tutti gli utenti.

Workflow completo in stile AppFlow

Ecco un esempio completo che combina tutte le strategie:

1. Setup iniziale (App v1.0.0)

# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
  --disable-auto-update metadata \
  --no-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. Rilascio Breaking Change (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
  --disable-auto-update metadata \
  --no-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Push degli Update su entrambe le versioni

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel v2 \
  --min-update-version "2.0.0"

4. Monitoraggio della distribuzione delle versioni

Usa la dashboard di Capgo per monitorare:

• Numero di utenti su v1 rispetto a v2
• Tasso di adozione dei bundle per versione
• Errori o crash per versione

5. Deprecare la vecchia versione

Quando l'utilizzo di v1 scende sotto la soglia:

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

Precedenza dei canali

In presenza di più configurazioni di canale, Capgo segue questo ordine di precedenza:

1. Override del dispositivo (Dashboard o API) - Priorità massima, visibile nella UI Device Override
2. Canale plugin locale tramite setChannel() - Salvato solo sul dispositivo e non visibile nella UI Device Override
3. defaultChannel in capacitor.config.ts
4. Canale predefinito (Impostazione Cloud) - Priorità minima

Esempio di precedenza

Se l'app di un utente ha defaultChannel: 'v2' ma forzi il loro dispositivo su 'beta' nel dashboard, riceveranno gli aggiornamenti dal 'beta' channel.

La UI di Device Override elenca solo gli override impostati dal dashboard o dal Public API. Chiamare setChannel() dall'app valida il channel con il backend, per poi salvarlo localmente sul dispositivo.

Best practice

1. Imposta sempre defaultChannel per le Major Version

// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3

// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually

2. Usa il Semantic Versioning

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Mantieni branch separati

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. Testa prima del rollout

# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

# Test on beta channel first
npx @capgo/cli@latest bundle upload \
  --channel beta \
  --auto-min-update-version

# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

5. Monitora la distribuzione delle versioni

Controlla regolarmente la tua dashboard:

• Gli utenti stanno passando a nuove versioni native?
• Le vecchie versioni ricevono ancora molto traffico?
• Dovresti deprecare i vecchi canali?

Confronto con Ionic AppFlow

Per i team che migrano da Ionic AppFlow, ecco come si confronta il version targeting di Capgo:

Funzionalità	Ionic AppFlow	Capgo
Routing basato sulla versione	Automatico in base alla versione nativa	Automatico tramite defaultChannel + strategie multiple
Versionamento semantico	Supporto base	Avanzato con --disable-auto-update (major/minor/patch)
Vincoli della versione nativa	Configurazione manuale in AppFlow dashboard	Integrato --min-update-version / --auto-min-update-version con canali metadata
Gestione canali	Web UI + CLI	Web UI + CLI + API
Override dei dispositivi	Controllo limitato a livello device	Controllo totale via Dashboard/API
Prevenzione auto-downgrade	Sì	Sì, tramite --no-downgrade
Manutenzione multi-versione	Gestione manuale branch/channel	Automatizzata con precedenza channel
Self-hosting	No	Sì (controllo totale)
Analytics delle versioni	Base	Metriche dettagliate per versione

Parità con AppFlow e oltre

Capgo offre tutte le funzionalità di version targeting offerte da AppFlow, con meccanismi di controllo aggiuntivi. Se usavi il version matching automatico di AppFlow, troverai Capgo altrettanto sicuro e più flessibile.

Risoluzione problemi

Gli utenti non ricevono gli aggiornamenti

Controlla quanto segue:

1. Assegnazione del Channel: Verifica che il dispositivo sia sul channel corretto

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. Vincoli di Versione: Controlla se il bundle ha requisiti di versione nativa

   • Dashboard → Bundles → Controlla la colonna “Native Version”

3. Impostazioni Semver: Verifica l'impostazione del disable-auto-update channel

   npx @capgo/cli channel list

4. Override del dispositivo: Verifica se il dispositivo ha un override manuale

   • Dashboard → Devices → Cerca dispositivo → Controlla channel/versione

Bundle inviato alla versione errata

1. Controlla il defaultChannel: Assicurati che il channel sia corretto capacitor.config.ts
2. Controlla l'upload del Bundle: Verifica che il bundle sia stato caricato sul channel previsto
3. Ispeziona la min update version: Conferma --min-update-version (o --auto-min-update-version) è stata impostata e il canale utilizza --disable-auto-update metadata

Breaking Changes sulle versioni precedenti

1. Soluzione Immediata: Forza i dispositivi interessati su un bundle sicuro
   • Dashboard → Dispositivi → Selezione multipla → Imposta versione
2. Soluzione a Lungo Termine: Crea canali versionati e mantieni branch separati
3. Prevenzione: Testa sempre gli update su dispositivi rappresentativi prima del rollout

Migrazione da Ionic AppFlow

Se stai migrando da Ionic AppFlow, il version targeting in Capgo funziona in modo molto simile, ma con maggiore flessibilità:

Mappatura dei concetti

Concetto AppFlow	Equivalente Capgo	Note
Canale di Deploy	Canale Capgo	Stesso concetto, più potente
Lock della versione Native	--min-update-version / --auto-min-update-version	Controllo più granulare
Priorità del canale	Precedenza canali (override → cloud → default)	Precedenza più trasparente
Target di deployment	Controllo tramite canale + semver	Strategie multiple disponibili
Canale di produzione	production channel (o qualsiasi nome)	Naming flessibile
Deployment basato su Git	Upload del bundle CLI da branch	Stesso workflow
Matching automatico della versione	defaultChannel + vincoli di versione	Potenziato con strategie multiple

Differenze chiave per utenti AppFlow

1. Maggiore controlloCon Capgo hai a disposizione diverse strategie (canali, semver, versione nativa) combinabili tra loro
2. Maggiore visibilitàLa dashboard mostra la distribuzione delle versioni e i problemi di compatibilità
3. Accesso API: Controllo programmatico completo sul version targeting
4. Self-hosting: Opzione per gestire il proprio server di update con la stessa logica di versione

Step di migrazione

1. Mappa i tuoi canali AppFlow sui canali Capgo (solitamente 1:1)
2. Imposta defaultChannel nella capacitor.config.ts per ogni versione major
3. Configura le regole semver se desideri il blocco automatico ai limiti di versione
4. Carica bundle specifici per versione usando --min-update-version (il canale deve usare la strategia metadata)
5. Monitora la distribuzione delle versioni nella dashboard di Capgo

Guida completa alla migrazione

Per istruzioni complete sulla migrazione, inclusa la sostituzione di SDK e il mapping di API, consulta la Guida alla migrazione da AppFlow a Capgo.

Pattern avanzati

Rollout graduale per versione

// Gradually migrate v1 users to v2
async function migrateUsers() {
  const deviceId = await CapacitorUpdater.getDeviceId()
  const rolloutPercentage = 10 // Start with 10%

  // Hash device ID to get deterministic percentage
  const hash = hashCode(deviceId) % 100

  if (hash < rolloutPercentage) {
    // User is in rollout group - migrate to v2
    await CapacitorUpdater.setChannel({ channel: 'v2' })
  }
}

Feature flag per versione

// Enable features based on native version
async function checkFeatureAvailability() {
  const info = await CapacitorUpdater.getDeviceId()
  const nativeVersion = info.nativeVersion

  if (compareVersions(nativeVersion, '2.0.0') >= 0) {
    // Enable features requiring v2.0.0+
    enableNewCameraFeature()
  }
}

A/B testing tra versioni

// Run A/B tests within same native version
async function assignABTest() {
  const nativeVersion = await getNativeVersion()

  if (nativeVersion.startsWith('2.')) {
    // Only A/B test on v2 users
    const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
    await CapacitorUpdater.setChannel({ channel: variant })
  }
}

Riassunto

Capgo offre diverse strategie per distribuire gli aggiornamenti a versioni specifiche:

1. Routing basato sui Channel: Separazione automatica delle versioni tramite defaultChannel
2. Versionamento Semantico: Impedisce aggiornamenti oltre i confini major/minor/patch
3. Vincoli di versione native: Richiede una versione native minima per i bundle
4. Prevenzione dell'auto-downgrade: Non distribuisce mai bundle più vecchi a versioni native più recenti
5. Override per dispositivo: Controllo manuale per test e targeting

Combinando queste strategie, puoi ottenere una distribuzione automatica degli aggiornamenti in stile AppFlow, con ancora più flessibilità e controllo. Scegli l'approccio che meglio si adatta al versioning e al workflow di deployment della tua app.

Per maggiori dettagli sulle singole funzionalità:

• Guida alle Breaking Changes - Strategia dettagliata per il versioning dei canali
• Gestione dei canali - Riferimento completo alla configurazione dei canali
• Comportamento degli aggiornamenti - Ritardi e condizioni delle versioni native

Continua da Version Targeting

Se stai usando Targeting delle versioni 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.