Obiettivo di Versione

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Questa guida spiega come consegnare automaticamente il pacchetto più compatibile agli utenti in base alla versione nativa dell'applicazione, simile all'approccio di Ionic AppFlow. Ciò garantisce una gestione semplificata degli aggiornamenti e una distribuzione più veloce, mentre prevenendo problemi di compatibilità.

Riepilogo

Capgo’s sistema di targeting delle versioni consente di:

Fornire aggiornamenti compatibili in modo automatico ai utenti in base alla loro versione nativa dell'app
Prevenire i cambiamenti che potrebbero rompere l'app da raggiungere versioni dell'app incompatibili
Gestire simultaneamente diverse versioni dell'app senza logica complessa
Eseguire aggiornamenti senza soluzione di continuità a specifici segmenti di utenti

Perché il targeting delle versioni è importante (Soprattutto per gli utenti di AppFlow)

Se sei familiare con Ionic AppFlow, sai quanto sia critico assicurarsi che gli utenti ricevano solo aggiornamenti compatibili. AppFlow ha automaticamente associato i pacchetti di aggiornamento live alle versioni native dell'applicazione, impedendo che il JavaScript incompatibile venisse consegnato alle versioni native più vecchie di code.

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

Controllo più granulare sulla corrispondenza delle versioni
Strategie multiple (canali, semver, vincoli native)
Migliore visibilità nella distribuzione delle versioni
API e CLI controllano insieme la gestione del dashboard

Questo approccio è particolarmente utile quando:

Hai utenti su diverse versioni maggiori dell'app (ad esempio, v1.x, v2.x, v3.x)
È necessario mantenere la compatibilità a ritroso mentre si implementano cambiamenti di rotazione
Desideri prevenire che i pacchetti più recenti rompano le versioni native più vecchie di code
Stai migrando gli utenti gradualmente da una versione all'altra
Stai migrando da AppFlow e desideri mantenere la stessa sicurezza di aggiornamento

Come Funziona

Capgo utilizza un approccio multi-layered per accoppiare gli utenti con aggiornamenti compatibili:

Restrizioni di Versione Nativa: Prevenire che i pacchetti vengano consegnati alle versioni native incompatibili
Routing basato sui canali: Inviare diverse versioni dell'applicazione a diversi canali di aggiornamento
Controllo delle versioni Semantici: Blocca automaticamente gli aggiornamenti ai confini di major/minor/patch
Override a livello di dispositivo: Scegli dispositivi o gruppi di utenti specifici

Flusso di versione di corrispondenza

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 canali

Questo è il approccio consigliato per la gestione dei cambiamenti di versione e degli aggiornamenti di versione maggiore. È simile al modello di consegna di AppFlow.

Scenario di esempio

App v1.x (100.000 utenti) → production canale
App v2.x (50.000 utenti con modifiche di compatibilità) → v2 canale
App v3.x (10.000 utenti beta) → v3 canale

Esecuzione

Passo 1: Configura i canali per ogni versione maggiore

// 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
    }
  }
};

Passo 2: Crea i canali

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create 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

Passo 3: Carica i pacchetti specifici 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

Benefici

Zero code modifiche - Il routing dei canali avviene automaticamente
Separazione chiara - Ogni versione ha il proprio pipeline di aggiornamento
Targeting flessibile - Aggiorna le versioni specifiche dei gruppi di versione
Rollout sicuro - Le modifiche di versione non raggiungono mai le versioni incompatibili

Strategy 2: Controlli di versioning semantici

Utilizza i controlli di versioning semantici integrati di Capgo per prevenire gli aggiornamenti oltre i confini delle versioni. Disabilita l'aggiornamento automatico tra versioni maggiori

Sottosezione intitolata “Disabilita l'aggiornamento automatico tra versioni maggiori”

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

Questa configurazione significa:

Gli utenti con versione dell'app 1.2.3 riceveranno aggiornamenti fino a 1.9.9
Gli utenti non RICEVERANNO la versione 2.0.0 automaticamente
Prevenire che i cambiamenti di rotta raggiungano le versioni native precedenti code
La comparazione 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

Sezione intitolata “Strategia 3: vincoli di versione native”

Condizione di ritardo di versione nativa

Quando si carica un bundle, è possibile specificare una versione minima di versione nativa:

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

Casi d'uso

Richiesta di nuovo plugin nativo

# Bundle needs Camera plugin added in v2.0.0
npx @capgo/cli bundle upload --native-version "2.0.0"

Breaking Native API Modifiche

# Bundle uses new Capacitor 6 APIs
npx @capgo/cli bundle upload --native-version "3.0.0"

Migrazione graduale

# Test bundle only on latest native version
npx @capgo/cli bundle upload \
  --channel beta \
  --native-version "2.5.0"

Strategia 4: Prevenzione del downgrade automatico

Prevenire agli utenti di ricevere pacchetti più vecchi della loro versione nativa corrente.

Abilita nelle impostazioni del canale

Nell'area di controllo Capgo:

Vai a Canali → Seleziona il tuo canale
Abilita “Disabilita l'autoabbassamento nativo”
Salva le modifiche

O via CLI:

npx @capgo/cli channel set production --disable-downgrade

Esempio

Dispositivo dell'utente: Versione nativa 1.2.5
Canale bundle: Versione 1.2.3
Risultato: L'aggiornamento è bloccato (sarebbe una riduzione di versione)

Questo è utile quando:

Gli utenti hanno installato manualmente una versione più recente dall'app store
Hai bisogno di assicurarti che gli utenti abbiano sempre le patch di sicurezza più aggiornate
Vuoi prevenire i bug di regressione

Schema 5: Targeting a livello di dispositivo

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

Forza Versione Specifica per 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' })
  }
}

Pannello di controllo Override dispositivo

Nel Capgo dashboard:

Vai a Dispositivi → Trova dispositivo
Clicca Imposta canale o Imposta versione
Override con canale o versione bundle specifica
Il dispositivo riceverà aggiornamenti da una fonte sovrascritta

Lavora con un flusso di lavoro completo AppFlow-Style

Ecco un esempio completo che combina tutte le strategie:

1. Configurazione iniziale (App v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

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

2. Rilascio Cambiamento di Versione (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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. Invia Aggiornamenti a Tutte le Versioni

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

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

4. Monitorare la Distribuzione delle Versioni

Usa il dashboard Capgo per monitorare:

Quanti utenti sono su v1 vs v2
Tassi di adozione del pacchetto per versione
Errori o crash per versione

5. Deprecare Versione Vecchia

Una volta che l'uso di v1 scende al di sotto del threshold:

# 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

Quando esistono più configurazioni di canale, Capgo utilizza questo ordine di precedenza:

Dispositivo Override (Pannello di controllo o API) - Priorità più alta e visibile nel Pannello di controllo del Dispositivo Override
Canale plugin locale via setChannel() - Memorizzato sul dispositivo solo e non mostrato nel Pannello di controllo del Dispositivo Override
canale predefinito in capacitor.config.ts
Canale predefinito (Impostazione Cloud) - Priorità più bassa

Pratiche Consigliate

1. Impostare sempre defaultChannel per le Versioni Principali

// ✅ 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. Utilizzare la versione semantica

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Mantieni rami 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 della distribuzione

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. Monitora la distribuzione delle versioni

Verifica regolarmente il tuo dashboard:

Gli utenti stanno aggiornando a versioni native più recenti?
Le vecchie versioni continuano a ricevere un alto traffico?
Dovresti deprecare i vecchi canali?

Confronto con Ionic AppFlow

Per le squadre che stanno migrando da Ionic AppFlow, ecco come la versione di targeting di Capgo si confronta:

Funzione	Ionic AppFlow	Capgo
Routing basato sulla versione	Routing automatico in base alla versione nativa	Routing automatico via `defaultChannel` + strategie multiple
Versioning semantico	Supporto base	Avanzato con `--disable-auto-update` (major/minor/patch)
Restrizioni di versione nativa	Configurazione manuale nel dashboard AppFlow	Supporto integrato `--native-version` flag in CLI
Gestione dei canali	Interfaccia web + CLI	Interfaccia web + CLI + API
Override dispositivi	Controllo limitato a livello di dispositivo	Controllo completo tramite Dashboard/API
Prevenzione del downgrade automatico	Sì	Sì via `--disable-downgrade`
Manutenzione di più versioni	Gestione di branch e canali manuali	Automatizzato con priorità di canale
Hosting autoamministrato	No	Sì (controllo completo)
Analisi della versione	Base	Metriche dettagliate per versione

Risoluzione dei problemi

Utenti che non ricevono aggiornamenti

Controlla i seguenti punti:

Assegnazione del canale: Verifica che il dispositivo sia sul canale corretto

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

Restrizioni di Versione: Controlla se il pacchetto ha richieste di versione native
- Pannello di controllo → Pacchetti → Controlla la colonna “Versione Nativa”
Impostazioni Semver: Verifica le impostazioni del canale disable-auto-update impostazioni
Fermata del terminale
```
npx @capgo/cli channel list
```
Override dispositivo: Controlla se il dispositivo ha un override manuale
- Dashboard → Dispositivi → Cerca dispositivo → Controlla canale/vers.

Bundle inviato alla versione sbagliata

Recensisci defaultChannel: Assicurati di avere il canale corretto in capacitor.config.ts
Controlla l'upload del bundle: Verifica se il bundle è stato caricato sul canale inteso
Verifica Versione Nativa: Conferma --native-version è stato utilizzato correttamente il flag

Cambiamenti Rilevanti che Affectano le Versioni Vecchie

Soluzione immediata: Imposta i dispositivi colpiti a bundle sicuro
- Pannello di controllo → Dispositivi → Selezione di massa → Imposta Versione
Soluzione a lungo termine: Crea canali versionati e mantieni rami separati
Prevenzione: Testa sempre gli aggiornamenti sui dispositivi rappresentativi prima della distribuzione

Migrazione da Ionic AppFlow

Se stai migrando da AppFlow Ionic, la versione targeting funziona in modo molto simile in Capgo, con maggiore flessibilità:

Mappatura dei concetti

Concetto AppFlow	Corrispettivo Capgo	Note
Canale di distribuzione	Canale Capgo	Lo stesso concetto, ma più potente
Versione nativa bloccata	`--native-version` bandiera	Controllo più granulare
Priorità del canale	Precedenza del canale (override → cloud → default)	Precedenza più trasparente
Destinazione di distribuzione	Canale + semver controlla	Disponibili più strategie
Canale di produzione	`production` canale (o qualsiasi nome)	Nominazione flessibile
Distribuzione basata su Git	CLI caricamento del bundle da ramo	Lo stesso workflow
Versione automatica	`defaultChannel` Versione con vincoli più	Rafforzato con strategie multiple

Differenze chiave per gli utenti di AppFlow

Più Controllo: Capgo vi dà strategie multiple (canali, semver, versione nativa) che possono essere combinate
Visibilità migliore: La dashboard mostra la distribuzione delle versioni e gli eventuali problemi di compatibilità
API Access: Controllo completo e programmabile sulla versione da targettare
Self-Hosting: Opzione per eseguire il proprio server di aggiornamento con la stessa logica di versione

Migration Steps

Map your AppFlow channels a Capgo canali (di solito 1:1)
Set defaultChannel in capacitor.config.ts per ogni versione maggiore
Configura regole semver se desideri il blocco automatico ai confini di versione
Carica bundle specifici per versione utilizzando --native-version flag
Monitora la distribuzione delle versioni nella dashboard di Capgo

Pattern avanzati

Rilascio 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' })
  }
}

Bandiere di feature 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()
  }
}

Test A/B 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 })
  }
}

Riepilogo

Capgo offre strategie multiple per la consegna di aggiornamenti specifici per versione:

Canali di routing: Separazione automatica della versione via defaultChannel
Versionamento semantico: Prevenire gli aggiornamenti attraverso i confini di versione maggiore/minore/patch
Restrizioni di versione native: Richiedere la versione minima nativa per i pacchetti
Prevenzione del downgrade automatico: Mai consegnare pacchetti più vecchi a versioni native più nuove
Override del dispositivo: Controllo manuale per la prova e il targeting

Combinate queste strategie, puoi raggiungere la consegna automatica di aggiornamenti con stile AppFlow, con ancora più flessibilità e controllo. Scegli l'approccio che meglio si adatta al flusso di versioning e di distribuzione del tuo app.

Per ulteriori informazioni sui dettagli specifici:

Guida alle modifiche di versione - Strategia di versioning del canale dettagliata
Gestione dei canali - Riferimento completo alla configurazione del canale
Comportamento dell'aggiornamento - Ritardi e condizioni di versione nativa

Continua da Version Targeting

Se stai utilizzando Version Targeting per pianificare la routing dei canali e la distribuzione in fasi, connettilo con Canali per i dettagli di implementazione in Canali, 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, e Soluzione di Targeting della Versione per il flusso di lavoro del prodotto in Soluzione di Targeting della Versione.