Target di Versione

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

Migrare da Ionic AppFlow?

Se stai passando 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 la Guida di migrazione da AppFlow per le istruzioni di migrazione passo dopo passo.

Panoramica

Capgo's sistema di targeting di versione consente di:

• Distribuire aggiornamenti compatibili in modo automatico agli utenti in base alla versione nativa dell'applicazione
• Prevenire i cambiamenti di rotta dalle versioni dell'applicazione incompatibili
• Gestire più versioni dell'applicazione in modo simultaneo senza logica complessa
• Eseguire aggiornamenti agli utenti specifici

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

Se sei abituato a 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 fornisce le stesse garanzie di sicurezza, con funzionalità aggiuntive:

• Maggiore controllo sulla versione di matching
• Strategie multiple (canali, semver, vincoli nativi)
• Migliore visibilità sulla distribuzione delle versioni
• API e CLI controllano insieme alla gestione della dashboard

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à verso il basso mentre esegui cambiamenti breaking
• Vuoi impedire che i pacchetti più recenti rompano le versioni native precedenti code
• Stai migrando gli utenti gradualmente da una versione all'altra
• Stai migrando da AppFlow e vuoi mantenere la stessa sicurezza di aggiornamento

Come Funziona

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

1. Restrizioni di versione nativa: Impedisci ai pacchetti di essere consegnati alle versioni native incompatibili
2. Routing basato sul canaleRouta diverse versioni dell'applicazione verso diverse canali di aggiornamento
3. Controlli di Semantica di VersioneRispetta automaticamente gli aggiornamenti ai confini di versione maggiore/minore/patch
4. Sovrascritture a livello di dispositivoMirare 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 defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

Strategia 1: Routing di versione basato sui canali

Questo è l'approccio consigliato per la gestione delle modifiche di rottura e delle 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: true,
      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: true,
      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: true,
      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

Routino 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 JavaScript code richiesta!

Vantaggi

• Zero code modifiche - Il routino del canale avviene automaticamente
• Separazione chiara - Ogni versione ha il proprio flusso di aggiornamento
• Targeting flessibile - Invia gli aggiornamenti a specifiche gruppi di versioni
• Rulli sicuri - Le modifiche di rottura non raggiungono le versioni incompatibili

Controllo delle versioni semantiche

Utilizza i controlli di versioning semantiche integrati di Capgo per evitare gli aggiornamenti tra i confini delle versioni.

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 la versione dell'app 1.2.3 riceveranno aggiornamenti fino a 1.9.9
• Gli utenti riceveranno NON la versione 2.0.0 automaticamente
• Preclude le modifiche di rotture da raggiungere le versioni native più vecchie code

Opzioni di controllo granulari

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (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 versione semantica (semver) per le versioni del tuo app. Assicurati che i numeri di versione seguano il MAJOR.MINOR.PATCH formato.

Schema 3: vincoli di versione native

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

Utilizzo della condizione di ritardo della versione nativa

Quando si carica un pacchetto, puoi 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 con versione nativa 1.x NON riceveranno questo pacchetto. Solo i dispositivi con 2.0.0+ lo riceveranno. Questo è perfetto per gli aggiornamenti che richiedono nuove API native o plugin.

Casi d'uso

1. Richiede nuovo plugin nativo

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

2. Modifiche native API che rompono

   # 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"

Strategia 4: Prevenzione del downgrade automatico

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

Abilita nelle impostazioni del canale

Nella dashboard Capgo:

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

O via CLI:

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

Esempio

• Dispositivo dell'utente: Versione nativa 1.2.5
• Bundle del canale: Versione 1.2.3
• RisultatoL'aggiornamento è bloccato (sarebbe una discesa)

Questo è utile quando:

• Gli utenti hanno installato manualmente una versione più recente dall'App Store
• È necessario assicurarsi che gli utenti abbiano sempre le patch di sicurezza più aggiornate
• Desideri prevenire i bug di regressione

Schema 5: Targeting a livello di dispositivo

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

Dashboard Override del dispositivo

Nel Capgo dashboard:

1. Vai a Dispositivi → Trova dispositivo
2. Clicca Imposta canale o Imposta versione
3. Sostituisci con canale o versione bundle specifico
4. Il dispositivo riceverà aggiornamenti da fonte sovrascritta

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 AppFlow completo

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: true,
      defaultChannel: 'production',
    }
  }
};

2. Rilascio di Modifica Rottura (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: true,
      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. Monitora la Distribuzione delle Versioni

Utilizza il dashboard Capgo per monitorare:

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

5. Deprecare Versione Obsoleta

Una volta che l'utilizzo 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 del Canale

When multiple channel configurations exist, Capgo uses this precedence order:

1. (Pannello di controllo o __CAPGO_KEEP_0__) - Priorità più alta (Dashboard or API) - Highest priority
2. via Cloudflare setChannel() chiamata
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 si sovrascrive il dispositivo dell'utente a 'beta' nel dashboard, riceveranno aggiornamenti dal 'beta' canale.

Pratiche raccomandate

1. Imposta sempre defaultChannel per le versioni maggiori

// ✅ 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. Monitora la distribuzione delle versioni

Controlla regolarmente il tuo dashboard:

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

Confronto con Ionic AppFlow

Per le squadre che stanno migrando da Ionic AppFlowEcco come la versione di Capgo si compara:

Funzione	Ionic AppFlow	Capgo
Routing basato sulla versione	Automatico in base alla versione nativa	Automatico tramite defaultChannel + strategie multiple
Versioning semantico	Supporto base	Avanzato con --disable-auto-update (major/minor/patch)
Restrizioni di versione nativa	Configurazione manuale nel dashboard di AppFlow	Integrato --native-version bandiera in CLI
Gestione del canale	Web UI + CLI	Web UI + CLI + API
Sovrascrizioni di dispositivo	Controllo limitato a livello di dispositivo	Controllo completo tramite Dashboard/API
Prevenzione della discesa automatica	Sì	Sì via --disable-downgrade
Manutenzione multi-versione	Gestione del ramo/canale manuale	Automatizzato con precedenza del canale
Auto-impostazione	No	Sì (controllo completo)
Analisi delle versioni	Basico	Dettagliati per versione

Parità di AppFlow e oltre

Capgo fornisce tutte le capacità di targeting delle versioni che AppFlow offriva, più meccanismi di controllo aggiuntivi. Se dipendevate da AppFlow per la versione automatica di matching, troverete Capgo altrettanto sicuro con più flessibilità.

Risoluzione dei problemi

Utenti che non ricevono aggiornamenti

Controlla i seguenti:

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: Verifica se il bundle richiede versioni native

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

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

   npx @capgo/cli channel list

4. : Verifica se il dispositivo ha impostato una sovrascrittura manualePannello di controllo → Dispositivi → Cerca dispositivo → Verifica canale/vers.

   • Copia negli appunti

Pacchetto Spedito alla Versione Errata

1. Recensisci defaultChannel: Assicurati di utilizzare il canale corretto in capacitor.config.ts
2. Controlla l'Upload del Pacchetto: Verifica che il pacchetto sia stato caricato nel canale inteso
3. Verifica la Versione Nativa: Conferma che --native-version flag è stato utilizzato correttamente

Modifiche Critiche che Affectano le Versioni Antiche

1. Soluzione di Emergenza: Sovrascrivi dispositivi interessati a bundle 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

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

Migrazione da Ionic AppFlow

Flusso di App	Capgo Equivalente	Note
Canale di distribuzione	Capgo Canale	Lo stesso concetto, più potente
Blocco di versione nativo	--native-version Bandiera	Controllo più dettagliato
Priorità del canale	Precedenza del canale (override → cloud → predefinito)	Precedenza più trasparente
Destinazione di distribuzione	Canale + semver controlla	Disponibili diverse strategie
Canale di produzione	production nome del canale (o qualsiasi altro nome)	Nominatività flessibile
Distribuzione basata su Git	CLI caricamento del pacchetto dall'origine	Lo stesso workflow
Compatibilità automatica con le versioni	defaultChannel + vincoli di versione	Rafforzato con più strategie

Differenze chiave per gli utenti di AppFlow

1. Maggiore Controllo: Capgo offre più 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 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 AppFlow ai canali Capgo (di solito 1:1)
2. Impostare defaultChannel in capacitor.config.ts per ogni versione maggiore
3. Configura le regole semver se desideri il blocco automatico ai confini delle versioni
4. Carica i pacchetti specifici per versione utilizzando --native-version flag
5. Monitorare la distribuzione delle versioni in Capgo dashboard

Guida di migrazione completa

Per le istruzioni di migrazione complete, compresa la sostituzione di SDK e la mappatura 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' })
  }
}

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 di A/B su diverse 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 per canaleSeparazione di versione automatica tramite defaultChannel
2. Versioning Semantico: Evita aggiornamenti tra versioni maggiori/minori/patch
3. Restrizioni di versione nativaRichiedi versione nativa minima per bundle
4. Prevenzione Riduzione VersioneNon consegnare mai bundle più vecchi a versioni native più nuove
5. Override dispositivoControllo manuale per il testing e la destinazione

Combinando queste strategie, puoi ottenere la consegna di aggiornamenti automatica 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 di versione - Strategia dettagliata di versioning del canale
• Gestione dei canali - Riferimento completo di configurazione del canale
• Comportamento dell'aggiornamento - Versione nativa ritardi e condizioni