Versione di destinazione

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

Stai migrando 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

Il sistema di targeting delle versioni di Capgo consente di:

• Rilasciare automaticamente aggiornamenti compatibili ai utenti in base alla loro versione nativa dell'app
• Prevenire modifiche che potrebbero rompere l'app dalle versioni dell'app incompatibili
• Gestire simultaneamente diverse versioni dell'app senza logica complessa
• Rilasciare aggiornamenti senza problemi a specifici segmenti di utenti

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

Se sei già familiarizzato con Ionic AppFlowRiconosci come critico 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:

• Controllo più granulare sull'associazione delle versioni
• Strategie multiple (canali, semver, vincoli native)
• Maggiore visibilità sulla distribuzione delle versioni
• API e CLI controllano insieme la gestione del dashboard

Questo 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 esegui cambiamenti di rotazione
• 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 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: 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 Versionamento Semantico: Blocca automaticamente gli aggiornamenti oltre i confini di versione maggiore/minore/patch
4. Impostazioni di Override del Livello di Dispositivo: Scegli dispositivi o gruppi di utenti specifici

Flusso di Versione di Confronto

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]

Schema 1: Routing delle Versioni basato sui Canali

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 versione) → v2 canale
• App v3.x (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 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

Routamento Automatico

Quando gli utenti aprono l'app, si connettono automaticamente al loro canale designato in base a defaultChannel nel loro bundle di app installato. Nessuna modifica al JavaScript code richiesta!

Benefici

• Zero code modifiche - Il routamento dei canali avviene automaticamente
• Separazione chiara - Ogni versione ha il proprio flusso di aggiornamento
• Targeting flessibile - Invia aggiornamenti a gruppi di versioni specifiche
• Rulli sicuri - Le modifiche di break non raggiungono le versioni incompatibili

Strategy 2: Controlli di versioning semantico

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

Disabilita Aggiornamento Automatico Oltre le Versioni Principali

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

Questa configurazione significa:

• 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
• Prevenire i cambiamenti di rotta che raggiungono le versioni native più vecchie 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 versione semantica obbligatoria

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

Strategy 3: vincoli di versione nativa

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

Con la condizione di ritardo di 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 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 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. Cambiamenti nativi 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"

Strategy 4: Prevenzione del downgrade automatico

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

Abilita nelle impostazioni del canale

Nel dashboard Capgo :

1. Vai a Canali → Scegli il tuo canale
2. Abilita “Disabilita l'autoabbassamento 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
• Bundle del canale: Versione 1.2.3
• Risultato: Aggiornamento bloccato (sarebbe una versione precedente)

Questo è utile quando:

• Utenti hanno installato manualmente una versione più recente dall'App Store
• Se hai bisogno di assicurarti che gli utenti abbiano sempre le patch di sicurezza più aggiornate
• Se 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 Sovrascrittura dispositivo

Nella Capgo dashboard:

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

Test aggiornamenti

Usa override di 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. Rilascio di modifica breaking (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 pacchetti per versione
• Errori o crash per versione

5. Deprecare la versione vecchia

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

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 nel pannello di controllo dell'override del dispositivo
2. Canale plugin locale via setChannel() - Salvato sul dispositivo solo e non visualizzato nell'interfaccia di override 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 si sovrascrive il loro dispositivo a 'beta' nell'area di controllo, riceveranno aggiornamenti da 'beta' Canale.

La UI di override del dispositivo elenca solo gli override impostati dal dashboard o da Public API. Chiamando setChannel() La chiamata dall'app verifica il canale con il backend, quindi lo memorizza localmente sul dispositivo.

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 del rilascio

# 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

Gli utenti stanno aggiornando alle versioni native più recenti?

• __CAPGO_KEEP_0__
• Le versioni vecchie continuano a ricevere un alto traffico?
• È necessario deprecare i canali vecchi?

Confronto con Ionic AppFlow

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

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

AppFlow Parity and Beyond

Capgo fornisce tutte le capacità di targeting della versione offerte da AppFlow, più meccanismi di controllo aggiuntivi. Se hai dipinto da AppFlow sul matching automatico delle versioni, troverai __CAPGO_KEEP_0__ altrettanto sicuro con più flessibilità. that AppFlow offered, plus additional control mechanisms. If you relied on AppFlow’s automatic version matching, you’ll find Capgo equally safe with more flexibility.

Sezione intitolata “Risoluzione dei problemi”

__CAPGO_KEEP_0__ provides all the version targeting capabilities that AppFlow offered, plus additional control mechanisms. If you relied on AppFlow’s automatic version matching, you’ll find __CAPGO_KEEP_0__ equally safe with more flexibility.

Controlla i seguenti elementi:

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

   • Dashboard → Pacchetti → Controlla la colonna “Versione nativa”

3. Impostazioni Semver: Verifica le impostazioni del canale disable-auto-update Fermata di sistema

   npx @capgo/cli channel list

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

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

Bundle inviato alla versione sbagliata

1. Recensisci defaultChannel: Assicurati di avere il canale corretto in capacitor.config.ts
2. Verifica l'upload del bundle: Verifica se il bundle è stato caricato sul canale inteso
3. Ispeziona versione nativa: Conferma --native-version flag è stato utilizzato correttamente

Cambiamenti significativi che interessano le versioni precedenti

1. Soluzione immediata: Imposta i dispositivi interessati su bundle sicuro
   • Dashboard → Dispositivi → Seleziona in massa → Imposta Versione
2. Soluzione a lungo termine: Crea canali versionati e mantieni rami separati
3. Prevenzione: Testa sempre gli aggiornamenti su dispositivi rappresentativi prima della distribuzione

Migrazione da Ionic AppFlow

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

Mapping dei concetti

AppFlow Concept	Capgo Equivalent	Note
Canale di distribuzione	Capgo Channel	Lo stesso concetto, ma più potente
Blocco di versione nativa	--native-version bandiera	Maggiore controllo granulare
Priorità del canale	Precedenza del canale (sovrascrivere → cloud → predefinito)	Precedenza più trasparente
Destinazione di distribuzione	Controllo del canale + semver	Disponibili diverse strategie
Canale di produzione	production canale (o qualsiasi nome)	Nominativo flessibile
Distribuzione basata su Git	CLI caricamento del bundle dalla branca	Lo stesso workflow
Versione automatica	defaultChannel Con vincoli di versione	Rafforzato con strategie multiple

Differenze chiave per gli utenti di AppFlow

1. Più Controllo: Capgo vi dà strategie multiple (canali, semver, versione nativa) che possono essere combinate
2. Visibilità Migliorata: Il dashboard mostra la distribuzione delle versioni e gli issue di compatibilità
3. API Access: Controllo programmatico completo sulla versione target
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 a Capgo canali (di solito 1:1)
2. Configura 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 version-specifico utilizzando --native-version flag
5. Monitorare la distribuzione delle versioni nel dashboard di Capgo

Guida completa di migrazione

Per le istruzioni di migrazione complete, comprese 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' })
  }
}

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

1. Routing basato sui canali: Separazione di versione automatica tramite defaultChannel
2. Semantic Versioning: Prevenire gli aggiornamenti attraverso i confini di versione maggiore/minore/patch
3. Native Version Constraints: Richiedere la versione minima nativa per i pacchetti
4. Auto-Downgrade Prevention: Mai consegnare bundle più vecchi a versioni native più nuove
5. Device Overrides: Controllo manuale per la prova e la destinazione

Combinando queste strategie, puoi raggiungere la consegna di aggiornamenti automatici AppFlow-style 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 dettagli sulle funzionalità specifiche:

• Guida ai Cambiamenti di Versione - Strategia dettagliata di versioning del canale
• Gestione dei canali - Riferimento completo di configurazione del canale
• Comportamento di aggiornamento - Ritardi e condizioni di versione native

Continua da Version Targeting

Version Targeting per pianificare la routing dei canali e la distribuzione in fasi, connettilo con Canali per i dettagli di implementazione in Canali, Section titled “Continua da Version Targeting” Canali per i dettagli di implementazione in Canali, Canali per i dettagli di implementazione in Canali, Soluzione di testing beta per il flusso di lavoro del prodotto in Soluzione di testing beta, e Soluzione di targeting versione per il flusso di lavoro del prodotto in Soluzione di targeting versione.