Targeta di Versione

Questa guida spiega come consegnare automaticamente la versione bundle più recente compatibile agli utenti in base alla loro 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à.

La migrazione da Ionic AppFlow?

Se sei passato da Ionic AppFlow, questa guida è particolarmente importante per te. AppFlow ha automaticamente corrisposto gli aggiornamenti alle versioni native, e Capgo offre la stessa capacità con ancora più controllo e flessibilità. Vedi il Guida di migrazione da AppFlow per le istruzioni di migrazione passo dopo passo.

Panoramica

il sistema di targeting delle versioni di Capgo consente di:

• Distribuire automaticamente aggiornamenti compatibili ai utenti in base alla loro versione nativa dell'applicazione
• Prevenire le modifiche che rompono da raggiungere versioni di app incompatibili
• Gestire diverse versioni di app contemporaneamente senza logica complessa
• Rilasciare aggiornamenti senza soluzione di continuità a specifici segmenti di utenti

Perché la versione di targeting è 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 corrisposto i pacchetti di aggiornamento live alle versioni native dell'applicazione, impedendo che il JavaScript incompatibile fosse consegnato alle versioni native precedenti code.

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

• Maggiore controllo sul matching delle versioni
• Strategie multiple (canali, semver, vincoli nativi)
• Migliore visibilità sulla distribuzione delle versioni
• API e CLI controllano insieme la gestione del pannello

Questa approccio è particolarmente utile quando:

• Hai utenti su diverse versioni maggiori della tua app (ad esempio, v1.x, v2.x, v3.x)
• Hai bisogno di mantenere la compatibilità inversa mentre rilasci cambiamenti breaking
• Vuoi impedire 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 desidera mantenere la stessa sicurezza degli aggiornamenti

Come Funziona

Capgo utilizza un approccio a strati multipli per abbinare gli utenti con aggiornamenti compatibili:

1. Restrizioni di Versione Nativa: Impedisce ai pacchetti di essere consegnati a versioni native incompatibili
2. Routing basato sui canali: Inoltra diverse versioni dell'applicazione a diversi canali di aggiornamento
3. Controlli di versioning semantico: Blocca automaticamente gli aggiornamenti tra i confini di versione maggiore/minore/patch
4. Override di livello dispositivo: Collega specifici dispositivi o gruppi di utenti

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]

Estrategia 1: Routing delle versioni basato sul canale

Questo è il approccio consigliato per la gestione delle modifiche 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 rottura) → v2 canale
• App v3.x (10.000 utenti beta) → v3 canale

Implementazione

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 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 bundle 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

Routinamento automatico

When gli utenti aprono l'app, si connettono automaticamente al loro canale designato in base al defaultChannel In loro installato bundle dell'app. Nessun cambiamento JavaScript code richiesto!

Benefici

• Zero code changes - La routing del canale avviene automaticamente
• - Separazione chiara - Ogni versione ha il suo proprio flusso di aggiornamento
• - Aggiornamenti push per gruppi di versioni specifiche - Eseguimenti di rotazione sicuri
• - Cambiamenti di versione che rompono mai raggiungono versioni incompatibili Eseguimenti di rotazione sicuri

Schema 2: Controlli di versione semantica

Usa Capgo’s controlli di versione semantica integrati per prevenire gli aggiornamenti tra i confini delle versioni. Disabilita Aggiornamento Automatico tra Versioni Principali

Sezione intitolata “Disabilita Aggiornamento Automatico tra Versioni Principali”

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

Utenti con versione dell'app

• riceveranno aggiornamenti fino a 1.2.3 __CAPGO_KEEP_0__ 1.9.9
• Utenti riceveranno NON riceveranno versioni 2.0.0 automaticamente
• Prevenire i cambiamenti di versione che raggiungono le versioni native più vecchie di 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

Richiesta di versioning semantico

Questa strategia funziona solo se segui la semantica versioning (semver) per le versioni del tuo app. Assicurati che i numeri di versione seguano il MAJOR.MINOR.PATCH formato.

Strategia 3: vincoli di versione nativa

Specificare una versione minima di app nativa (min_update_version) su ogni bundle, in modo che Capgo lo consegni solo ai dispositivi con binario nativo abbastanza aggiornato.

Questa utilizza la strategia di metadati del canale metadati del canale--disable-auto-update metadata( --min-update-version o --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Sottosezione intitolata “Abilita la targeting dei metadati sul canale”

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

Sottosezione intitolata “Abilita la targeting dei metadati sul canale”

Fermata del terminale

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

Ora lascia Capgo stabilire il livello di base dalle compatibilità dei pacchetti nativi:

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

Come funziona

Con la strategia dei metadati, i dispositivi con il livello di base nativo (version_build) che è inferiore al pacchetto ( min_update_version ) saltano l'aggiornamento. Solo i dispositivi su quella versione o superiore ricevono l'aggiornamento. Vedi Compatibilità per --auto-min-update-version dettagli.

Uso del caso

1. Richiede nuovo plugin nativo

   # 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 native API

   # 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 del downgrade automatico

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

Abilita nelle Impostazioni del Canale

Sul Capgo dashboard:

1. Vai a Canali context
2. Seleziona il tuo canale Abilita
3. “Disabilita l'autoabbassamento sotto la versione nativa”

Or via CLI:

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

Esempio

• Dispositivo dell'utente: Versione nativa 1.2.5
• Pacco del canale: Versione 1.2.3
• Risultato: L'aggiornamento è bloccato (sarebbe una versione precedente)

Questo è utile quando:

• Gli utenti hanno installato manualmente una versione più recente dal negozio di app
• Hai bisogno di assicurarti che gli utenti abbiano sempre le patch di sicurezza più recenti
• Vuoi prevenire i bug di regressione

Strategia 5: Targeting a livello di dispositivo

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

Forza versione specifica per le prove

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 pannello di controllo:

1. Vai a Dispositivi → Trova dispositivo
2. Clicca Aggiungi canale o Seleziona il canale o la versione specifica per sovrascrivere le impostazioni predefinite
3. Il dispositivo riceverà aggiornamenti dall'origine sovrascritta
4. Aggiornamenti di testing

Utilizza le sovrascritture del dispositivo per testare gli aggiornamenti sul tuo dispositivo prima di distribuirli a tutti gli utenti.

Flusso di lavoro completo AppFlow-Style

Sottosezione intitolata “Flusso di lavoro completo AppFlow-Style”

1. Configurazione iniziale (App v1.0.0)

Aggiungi versione

# 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. Cambiamento di rilascio (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. Invia aggiornamenti a 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. Monitorare la distribuzione delle versioni

Utilizza il Capgo dashboard per tracciare:

• Quanti utenti sono su v1 vs v2
• Tassi di adozione dei bundle per versione
• Errori o crash per versione

5. Deprecare la versione vecchia

Una volta che l'utilizzo di v1 scende sotto il 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 del canale

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

1. Override del dispositivo (Pannello di controllo o API) - Priorità più alta e visibile nell'interfaccia di Override del dispositivo
2. Canale del plugin locale via setChannel() - Memorizzato sul dispositivo solo e non mostrato nell'interfaccia di Override del dispositivo
3. defaultChannel in capacitor.config.ts
4. Canale predefinito (Impostazione Cloud) - Priorità più bassa

Esempio di Precedenza

Se un'applicazione di un utente ha defaultChannel: 'v2' ma si sovrascrive il dispositivo con 'beta' nel dashboard, riceveranno aggiornamenti dal 'beta' canale.

Il pannello di sovrascrizione del dispositivo elenca solo le sovrascrizioni impostate dal dashboard o da Public API. Chiamando setChannel() valida il canale con il backend, quindi lo memorizza localmente sul dispositivo.

Pratiche Raccomandate

1. Imposta 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. Utilizza 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

# 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. Monitorare la distribuzione delle versioni

Controlla regolarmente il tuo dashboard:

• Gli utenti stanno aggiornando a versioni native più recenti?
• Le vecchie versioni stanno ancora ricevendo un traffico elevato?
• Devi deprecare i vecchi canali?

Confronto con Ionic AppFlow

Per le squadre che stanno migrando da Ionic AppFlowEcco come Capgo si differenzia per quanto riguarda la versione di destinazione:

Caratteristica	Ionic AppFlow	Capgo
Versionamento basato sulla versione	Versionamento basato sulla versione nativa	Versionamento basato sulla versione via defaultChannel + strategie multiple
Versionamento semantico	Sostegno base	Sostegno avanzato con --disable-auto-update (major/minor/patch)
Versioni native con vincoli	Configurazione manuale nel dashboard di AppFlow	Integrato --min-update-version / --auto-min-update-version con canali di metadati
Gestione canali	Interfaccia web + CLI	Interfaccia web + CLI + API
Override dispositivo	Controllo limitato a livello di dispositivo	Controllo completo tramite Dashboard/API
Prevenzione del downgrade automatico	Sì	Sì via --no-downgrade
Manutenzione multi-versione	Gestione manuale di branch e canali	Automatizzato con precedenza di canale
Auto hosting	No	Sì (controllo completo)
Analisi di versione	Basico	Metriche dettagliate per versione

Parietà di AppFlow e oltre

Capgo fornisce tutte le funzionalità di targeting versione che AppFlow offriva, più meccanismi di controllo aggiuntivi. Se avete dipenduto dalle versioni di AppFlow automatiche, troverete Capgo altrettanto sicuro con più flessibilità.

Risolvere i Problemi

Sezione intitolata “Risolvere i Problemi”

Sezione intitolata “Utenti che non ricevono Aggiornamenti”

1. Controllate le seguenti cose:Assegnazione del Canale

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

2. Copia negli Appunti (Copia in Clipboard) non translated as it is a literal token, but translated to : Controlla se il bundle ha requisiti di versione native

   • Dashboard → Bundle → Controlla la colonna "Versione nativa"

3. Impostazioni Semver: Verifica le impostazioni del canale disable-auto-update impostazione

   npx @capgo/cli channel list

4. Override dispositivo: Controlla se il dispositivo ha un override manuale

   • Dashboard → Dispositivi → Cerca dispositivo → Controlla canale/versione

Bundle consegnato alla versione sbagliata

1. Verifica canale predefinito: Assicurati di avere il canale corretto in capacitor.config.ts
2. Controlla l'upload del pacchetto: Verifica se il pacchetto è stato caricato sul canale inteso
3. Verifica la versione minima dell'aggiornamento: Conferma --min-update-version (o --auto-min-update-version) è stato impostato e il canale utilizza --disable-auto-update metadata

Modifiche di Rilascio che Affectano le Versioni Antiche

1. Soluzione immediata: Sovrascrivi i dispositivi colpiti con il pacchetto sicuro
   • Dashboard → Dispositivi → Selezione di massa → Imposta Versione
2. Soluzione a Lungo Termine: Crea canali con versione e mantieni rami separati
3. Prevenzione: Testa sempre gli aggiornamenti su dispositivi rappresentativi prima della distribuzione

Migrazione da Ionic AppFlow

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

Mappatura dei Concetti

AppFlow Concept	Capgo Equivalent	Note
Canale di distribuzione	Capgo Canale	Lo stesso concetto, ma più potente
Versione nativa bloccata	--min-update-version / --auto-min-update-version	Possibilità di controllo più granulare
Priorità del canale	Precedenza del canale (override → cloud → default)	Precedenza più trasparente
Obiettivo di distribuzione	Canale + semver controlla	Disponibili diverse strategie
Canale di produzione	production canale (o qualsiasi nome)	Nominazione flessibile
Distribuzione basata su Git	CLI caricamento del bundle dalla branca	Stesso workflow
Compatibilità automatica con la versione	defaultChannel + vincoli di versione	Rafforzato con diverse strategie

Differenze chiave per gli utenti di AppFlow

1. Piu Controllo: Capgo offre strategie multiple (canali, semver, versione nativa) che possono essere combinate
2. Piu Visibilita: Il dashboard mostra la distribuzione delle versioni e gli eventuali problemi di compatibilita
3. API Accesso: Controllo programmatico completo sulla versione di destinazione
4. Auto-Hosting: Opzione per eseguire il proprio server di aggiornamento con la stessa logica di versione

Passaggi di Migrazione

1. Mappa i canali di AppFlow per Capgo canali (di solito 1:1)
2. Imposta defaultChannel in capacitor.config.ts per ogni versione maggiore
3. Configura le regole semver se desideri il blocco automatico ai confini di versione
4. Carica bundle specifici per versione utilizzando --min-update-version (il canale deve utilizzare la strategia di metadata)
5. Monitora la distribuzione delle versioni in Capgo dashboard

Guida di Migrazione Completa

Per istruzioni di migrazione complete, comprese le sostituzioni di SDK e le mappature di API, vedere il Guida di Migrazione da AppFlow a Capgo.

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

Flag 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 di 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 fornisce diverse strategie per la consegna di aggiornamenti specifici per versione:

1. Routing basato sul canale: Separazione automatica delle versioni tramite defaultChannel
2. : Prevenire gli aggiornamenti tra confini di versione maggiore/minore/patchRestrizioni native di versione
3. : Richiedere la versione minima nativa per i pacchettiPrevenzione del downgrade automatico
4. Automatic version separation via Semantic Versioning: Mai distribuire bundle più vecchi a versioni native più nuove
5. Device Overrides: Controllo manuale per test e targeting

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

Per ulteriori informazioni sui dettagli specifici:

• Guida alle modifiche significative - Strategia dettagliata di versioning dei canali
• Gestione dei canali - Riferimento completo di configurazione dei canali
• Comportamento degli aggiornamenti - Ritardi e condizioni delle versioni native

Continua da qui: Targeting delle versioni

Se stai utilizzando Versione di targeting per pianificare la routing dei canali e la distribuzione in fase di testing, connettilo con Canali per i dettagli di implementazione in Canali, Canali per i dettagli di implementazione in Canali, Canali Soluzione di testing beta per il flusso di lavoro del prodotto in Soluzione di testing beta, e __CAPGO_KEEP_0__ Soluzione di Targeting della Versione per il flusso di lavoro del prodotto nella Soluzione di Targeting della Versione.