Target di Versione

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. Questo garantisce una gestione degli aggiornamenti semplificata e una distribuzione più rapida, 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 il Guida di migrazione da AppFlow per le istruzioni di migrazione passo dopo passo.

Panoramica

Capgo’s sistema di targeting delle versioni consente di:

• Distribuire automaticamente aggiornamenti compatibili ai utenti in base alla versione nativa dell'applicazione
• Prevenire modifiche che rompono il codice da raggiungere versioni di app incompatibili
• Gestisci diverse versioni di app contemporaneamente senza logica complessa
• Esegui 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 cruciale assicurarsi che gli utenti ricevano solo aggiornamenti compatibili. AppFlow ha automaticamente corrisposto pacchetti di aggiornamento live ai bundle nativi, impedendo che JavaScript incompatibile fosse consegnato a versioni native più vecchie di code.

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

• Maggiore controllo sulla corrispondenza delle versioni
• Multiple strategie (canali, semver, vincoli nativi)
• Visibilità migliore nella distribuzione delle versioni
• API e CLI controllo insieme alla gestione del pannello

Questo approccio è particolarmente utile quando:

• Hai utenti su diverse versioni maggiori del tuo app (ad esempio, v1.x, v2.x, v3.x)
• Hai bisogno di mantenere la compatibilità con le versioni precedenti mentre esegui cambiamenti di rottura
• Vuoi impedire che i bundle 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-strato per accoppiare gli utenti con aggiornamenti compatibili:

1. Restrizioni di Versione Nativa: Prevenire i pacchetti da essere consegnati a versioni native incompatibili
2. Routing basato sui Canali: 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 di Livello di Dispositivo: Targetare dispositivi specifici o gruppi di utenti

Flusso di Accoppiamento di Versione

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]

Strategy 1: Routing per canale di versione

Questo è il metodo consigliato per gestire i cambiamenti significativi e le 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

Sezione intitolata “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

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 pipeline di aggiornamento
• Targeting flessibile - Aggiornamenti push per gruppi di versioni specifiche
• Rollout sicuro - Cambiamenti di versione non raggiungono le versioni incompatibili

Strategy 2: Controlli di versioning semantico

Utilizza i controlli di versionamento semantico integrati di Capgo per impedire gli aggiornamenti tra i confini delle versioni.

Disabilita 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 la versione dell'app 1.2.3 riceveranno gli aggiornamenti fino a 1.9.9
• Gli utenti non riceveranno la versione automaticamente 2.0.0 Capacitor
• Previene che i cambiamenti di base non raggiungano 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.

Strategia 3: vincoli di versione native

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

Utilizzo della versione nativa Condizione di ritardo

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

# 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 bundle. Solo i dispositivi su 2.0.0+ lo riceveranno. Questo è perfetto per gli aggiornamenti che richiedono nuovi API nativi o plugin.

Casi d'uso

1. Richiesta di 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 di 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 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 nativo”
3. Salva le modifiche

Ora 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 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ù recenti
• 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 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 Dispositivo Override

Nel Capgo pannello di controllo:

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

Test delle 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

1. Configurazione iniziale (App v1.0.0)

Finestra del terminale

# 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 entrambe 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 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 limite:

# 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 l'ordine di precedenza seguente:

1. Override dispositivo (Pannello di controllo o API) - Priorità più alta
2. Override Cloud via setChannel() chiamata
3. canale predefinito in capacitor.config.ts
4. Canale predefinito (impostazione Cloud) - Priorità più bassa

Esempio di Precedenza

Se l'applicazione di un utente ha defaultChannel: 'v2' ma sostituisci il loro dispositivo con 'beta' nel pannello di controllo, riceveranno aggiornamenti dal 'beta' canale.

Pratiche Consigliate

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

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

• I utenti stanno aggiornando a versioni native più recenti?
• Le vecchie versioni stanno ancora ricevendo 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:

Caratteristica	Ionic AppFlow	Capgo
Routing basato sulla versione	Basato automaticamente sulla versione nativa	Automatico tramite defaultChannel + strategie multiple
Versioning semantico	Supporto base	Avanzato con --disable-auto-update (major/minor/patch)
Restrizioni sulla versione nativa	Configurazione manuale nel dashboard di AppFlow	Integrato --native-version flag in CLI
Gestione del canale	Interfaccia Web + CLI	Interfaccia Web + CLI + API
Sovrascritture del dispositivo	Controllo limitato a livello di dispositivo	Controllo completo tramite Dashboard/API
Prevenzione del downgrade automatico	Sì	Sì via --disable-downgrade
Manutenzione delle diverse versioni	Gestione della branca/canale manuale	Automatizzato con priorità di canale
Auto-impostazione	No	Sì (controllo completo)
Analisi delle versioni	Base	Metriche dettagliate per versione

Parità e oltre di AppFlow

Capgo fornisce tutte le capacità di targeting delle versioni che AppFlow offriva, più meccanismi di controllo aggiuntivi. Se hai dipinto da AppFlow automatico matching delle versioni, troverai Capgo altrettanto sicuro con più flessibilità.

Risoluzione dei problemi

Utenti che non ricevono aggiornamenti

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 Impostazioni Semver

   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 è stata utilizzata correttamente la flag

Cambiamenti Rilevanti che Affectano le Versioni Antiche

1. Soluzione di Emergenza: Imposta i dispositivi colpiti su bundle sicuro
   • Pannello di controllo → Dispositivi → Selezione di massa → Imposta Versione
2. Soluzione a Lungo Termine: Crea canali versionati e mantieni rami separati
3. Prevenzione: Testa sempre le aggiornamenti su dispositivi rappresentativi prima della distribuzione

Migrazione da Ionic AppFlow

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

Mappatura dei concetti

Concetto AppFlow	Capgo Equivalente	Note
Canale di distribuzione	Capgo Canale	Lo stesso concetto, ma con maggiore potenza
Blocco Versione Nativa	--native-version flag	Maggiore controllo granulare
Priorità del Canale	Precedenza del Canale (override → cloud → default)	Precedenza più trasparente
Destinazione di Distribuzione	Canale + controlli semver	Disponibili diverse strategie
Canale di Produzione	production canale (o qualsiasi nome)	Nominazione flessibile
Deployimento basato su Git	CLI caricamento del pacchetto dall'assegnazione	Lo stesso workflow
Compatibilità automatica della versione	defaultChannel Restrizioni di versione più avanzate	Sviluppato con strategie multiple

Differenze chiave per gli utenti di AppFlow

1. Maggiore controllo: Capgo offre strategie multiple (canali, semver, versione nativa) che possono essere combinate
2. Visibilità migliore: Il dashboard mostra la distribuzione delle versioni e gli eventuali problemi di compatibilità
3. API Accesso: Controllo completo programmatico 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 a Capgo canali (di solito 1:1)
2. Impostare defaultChannel in capacitor.config.ts per ogni versione maggiore
3. Configurare le regole semver Se desideri il blocco automatico ai confini di versione
4. Carica bundle specifici per versione utilizzando --native-version flag
5. Monitorare la distribuzione delle versioni nella dashboard di Capgo

Guida completa di migrazione

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

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 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 per Canale: Separazione automatica della versione tramite defaultChannel
2. Versionamento Semantico: Prevenire gli aggiornamenti attraverso i confini di versione maggiore/minore/patch
3. Restrizioni di Versione Nativa: Richiedere la versione minima nativa per i pacchetti
4. Prevenzione del Downgrade Automatico: Non consegnare mai pacchetti più vecchi a versioni native più nuove
5. Override del Dispositivo: Controllo manuale per la prova e il targeting

Combinate queste strategie per raggiungere il tipo di aggiornamento automatico di AppFlow con ancora più flessibilità e controllo. Scegli l'approccio che meglio si adatta al flusso di versione e di distribuzione del tuo app.

Per ulteriori dettagli sulle funzionalità specifiche:

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