Versione di Riferimento

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

Stai migrando da Ionic AppFlow?

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

Panoramica

il sistema di targeting delle versioni di Capgo consente di:

• Invia automaticamente aggiornamenti compatibili ai utenti in base alla versione nativa del loro app
• Prevenire modifiche che rompono le versioni dell'app incompatibili
• Gestire più versioni dell'app contemporaneamente senza logica complessa
• Rilascia aggiornamenti senza intoppi su specifiche fasce di utenti

Perché la versione di destinazione è importante (specialmente per gli utenti di AppFlow)

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

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

• Maggiore controllo granulare sulla corrispondenza delle versioni
• Strategie multiple (canali, semver, vincoli native)
• Migliore visibilità sulla distribuzione delle versioni
• Ecco come API e CLI controllano insieme alla gestione del pannello

Questa approccio è particolarmente utile quando:

• Hai utenti su diverse versioni principali dell'app (ad esempio, v1.x, v2.x, v3.x)
• Hai bisogno di mantenere la compatibilità a ritroso mentre rilasci cambiamenti che rompono
• Vuoi impedire che i pacchetti più recenti rompano le code native più vecchie
• Stai migrando gli utenti gradualmente da una versione all'altra
• Stai migrando da AppFlow e vuoi mantenere la stessa sicurezza degli aggiornamenti

Come Funziona

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

1. Restrizioni di versione nativa: Prevenire i bundle da essere consegnati a versioni native incompatibili
2. Routing basato sul canale: Inviare versioni diverse dell'app a canali di aggiornamento diversi
3. Controlli di versioning semantico: Bloccare automaticamente gli aggiornamenti ai confini di major/minor/patch
4. Override a livello di dispositivo: Targetare dispositivi specifici 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]

Strategia 1: Routing di versione basato sul canale

Questo è l'approccio consigliato per la gestione dei cambiamenti di versione e delle versioni maggiori. È simile al modello di consegna di AppFlow. Esempio di Scenario

Sezione intitolata “Esempio di Scenario”

• (100.000 utenti) → canale production App v2.x
• (50.000 utenti con cambiamenti di versione) → canale v2 App v3.x
• (aggiornamento con cambiamenti di versione) → (10.000 utenti beta) → v3 canale

Implementazione

Passo 1: Configura i canali per ogni versione principale

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

Passaggio 3: Carica bundle specifico 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 loro canale designato in base al defaultChannel nel loro bundle di app installato. Nessuna modifica al JavaScript code richiesta!

Vantaggi

• Zero code modifiche - La routing dei canali avviene automaticamente
• Separazione chiara - Ogni versione ha il proprio flusso di aggiornamento
• Targeting flessibile - Invia aggiornamenti a gruppi di versioni specifiche
• Rollout sicuro - Le modifiche di rottura non raggiungono le versioni incompatibili

Strategy 2: Controlli di versioning semantico

Utilizza i controlli di versioning semantico integrati di Capgo per prevenire gli aggiornamenti oltre i confini delle versioni. per prevenire gli aggiornamenti oltre i confini delle versioni.

Disabilita l'aggiornamento automatico tra versioni principali

# 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 automaticamente 2.0.0 Previene i cambiamenti di rotta che raggiungono le versioni native precedenti __CAPGO_KEEP_0__
• Prevents breaking changes from reaching older native code
• The comparison uses the native baseline sent as version_build

Opzioni di controllo granulari

# 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 versione semantica obbligatoria

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

Strategia 3: vincoli di versione native

Specificare i requisiti minimi di versione nativa per i pacchetti per prevenire la consegna a dispositivi incompatibili.

Condizione di ritardo di versione nativa

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

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

Come Funziona

I dispositivi sulla versione nativa 1.x NON riceveranno questo pacchetto. Solo i dispositivi su 2.0.0+ lo riceveranno. Questo è perfetto per gli aggiornamenti che richiedono nuovi API nativi o plugin.

Uso dei casi

1. Nuovo Plugin Nativo Richiesto

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

2. Modifiche Native API

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

3. Migrazione Graduale

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

Prevenzione della Riduzione Automatica

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

Abilita nelle impostazioni del canale

Nell'area di controllo Capgo:

1. Vai a Canali → Seleziona il tuo canale
2. Abilita “Disabilita l'auto-downgrade nativo”
3. Salva le modifiche

O via CLI:

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

Esempio

• Dispositivo dell'utente: Versione nativa 1.2.5
• Pacco di canale: Versione 1.2.3
• Risultato: Aggiornamento bloccato (sarebbe una versione precedente)

Questo è utile quando:

• Gli utenti hanno installato manualmente una versione più recente dalla store 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 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' })
  }
}

Dashboard Override Dispositivo

Nella dashboard Capgo :

1. Vai a Dispositivi → Trova dispositivo
2. Clicca Imposta Canale o Imposta Versione
3. Sostituisci con una versione specifica di canale o pacchetto
4. Il dispositivo riceverà aggiornamenti dalla fonte sovrascritta

Test Aggiornamenti

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

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

capacitor.config.ts

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

2. Cambio di rilascio (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

Utilizza il dashboard Capgo 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)

Priorità dei canali

Quando esistono più configurazioni di canali, Capgo utilizza questo ordine di priorità:

1. Sovrascrittura del dispositivo (Pannello di controllo o API) - Priorità più alta e visibile nel Pannello di controllo per la sovra-scrittura del dispositivo
2. Canale plugin locale via setChannel() - Memorizzato sul dispositivo solo e non mostrato nel Pannello di controllo per la sovra-scrittura del dispositivo
3. canale predefinito 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 sovrascrive il loro dispositivo a 'beta' nel dashboard, riceveranno aggiornamenti dal 'beta' canale.

L'interfaccia utente di Override Device elenca solo le sovrascritture impostate dal dashboard o da Public API. Chiamando setChannel() dall'applicazione, si verificano il canale con il backend, quindi lo si memorizza localmente sul dispositivo.

Pratiche Raccomandate

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

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

Controlla regolarmente il tuo dashboard:

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

Confronto con Ionic AppFlow

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

Caratteristica	Ionic AppFlow	Capgo
Routing basato sulla versione	Automatico in base alla versione nativa	Automatico via defaultChannel + strategie multiple
Versioning semantico	Supporto base	Avanzato con --disable-auto-update (major/minor/patch)
Vincoli di versione nativa	Configurazione manuale nel dashboard di AppFlow	Integrato --native-version flag in CLI
Gestione del canale	Web UI + CLI	Web UI + CLI + API
Override del dispositivo	Controllo limitato a livello di dispositivo	Controllo completo tramite Dashboard/API
Prevenzione del downgrade automatico	Sì	Sì via --disable-downgrade
Manutenzione multi-versione	Gestione manuale di branch e canali	Automatizzato con precedenza di canale
Auto-hosting	No	Sì (controllo completo)
Analisi di versione	Base	Metriche dettagliate per versione

Parietà di AppFlow e oltre

Capgo fornisce tutte le capacità di targeting delle versioni che AppFlow offriva, più meccanismi di controllo aggiuntivi. Se dipendevate dalle versioni automatiche di AppFlow, troverete Capgo altrettanto sicuro con più flessibilità.

Risoluzione dei problemi

Utenti che non ricevono aggiornamenti

Controlla il seguente:

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

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

2. Restrizioni di versione: Controlla se il pacchetto ha richieste di versione native

   • Pannello di controllo → Pacchetti → Verifica la colonna "Versione nativa"

3. Impostazioni Semver: Verifica il canale di " disable-auto-update __CAPGO_KEEP_0__"

   npx @capgo/cli channel list

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

   • Pannello di controllo → Dispositivi → Cerca dispositivo → Verifica canale/versione

Pacchetto consegnato alla versione sbagliata

1. Recensisci defaultChannel: Assicurati di utilizzare il canale corretto in capacitor.config.ts
2. Verifica l'upload del bundle: Verifica che il bundle sia stato caricato sul canale inteso
3. Ispeziona la versione nativa: Conferma --native-version segliere la bandiera è stata utilizzata correttamente

Cambiamenti Rilevanti che Affectano le Versioni Vecchie

1. Soluzione di Emergenza: Sovrascrivi i dispositivi colpiti con il bundle sicuro
   • Pannello di controllo → Dispositivi → Seleziona in massa → Imposta la versione
2. Soluzione a Lungo Termine: Crea canali versionati e gestisci rami separati
3. Prevenzione: Testa sempre gli aggiornamenti su dispositivi rappresentativi prima del rollout

Migrazione da Ionic AppFlow

Ionic AppFlow , la versione di destinazione funziona in modo molto simile a __CAPGO_KEEP_0__, con maggiore flessibilità:, version targeting works very similarly in Capgo, with improved flexibility:

Rami di AppFlow

Migrazione da Ionic AppFlow	Capgo Equivalent	Note
Canale di distribuzione	Capgo Canale	Stesso concetto, più potente
Versione nativa bloccata	--native-version flag	Controllo più dettagliato
Priorità del canale	Precedenza del canale (override → cloud → default)	Precedenza più trasparente
Destinazione di distribuzione	Canale + semver controlla	Strategie multiple disponibili
Canale di produzione	production canale (o qualsiasi nome)	Nominazione flessibile
Deploy con Git	CLI caricamento del bundle da ramo	Lo stesso workflow
Versione automatica	defaultChannel Vincoli di versione con +	Rafforzato con strategie multiple

Differenze chiave per gli utenti di AppFlow

1. Più Controllo: Capgo offre diverse strategie (canali, semver, versione nativa) che possono essere combinate
2. Visibilità Migliorata: La dashboard mostra la distribuzione delle versioni e gli eventuali problemi di compatibilità
3. API Accesso: Controllo completo programmatico sulla versione di destinazione
4. Self-Hosting: Opzione per eseguire il proprio server di aggiornamento con la stessa logica di versione

Passaggi di Migrazione

1. Mappa i canali AppFlow a Capgo canali (di solito 1:1)
2. Imposta defaultChannel in capacitor.config.ts per ogni versione principale
3. Configura le regole semver se desideri il blocco automatico ai confini di versione
4. Carica bundle specifici per versione utilizzando --native-version flag
5. Monitora la distribuzione delle versioni nel dashboard Capgo

Guida completa di migrazione

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

Modelli avanzati

Esecuzione 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 Flags 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 fornisce strategie multiple per la consegna di aggiornamenti specifici per versione:

1. Routing basato sui canali : Separazione automatica della versione via defaultChannel
2. Semantic Versioning : Prevenire gli aggiornamenti attraverso i confini di versione maggiore/minore/patch
3. Versioni native vincolate : Richiedere la versione minima nativa per i pacchetti
4. Prevenzione del downgrade automatico : Non consegnare mai pacchetti più vecchi alle versioni native più nuove
5. Device Overrides: Control manuale per test e targeting

Combinando queste strategie, puoi raggiungere l'aggiornamento automatico di 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 alla configurazione dei canali
• Comportamento dell'aggiornamento - Ritardi e condizioni native della versione

Continua da Targeting delle versioni

If sei stai utilizzando Versione 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 Versione Targeting per il flusso di prodotto nella Version Targeting Solution.