Targeting 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 AppFlowCiò garantisce una gestione degli aggiornamenti semplificata e un lancio più rapido, evitando problemi di compatibilità.

Migrare da Ionic AppFlow?

Se stai passando da Ionic AppFlow, questa guida è particolarmente importante per te. AppFlow sincronizzava automaticamente 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

Capgo's sistema di targeting delle versioni consente di:

• Invia automaticamente aggiornamenti compatibili ai utenti in base alla versione nativa dell'app
• Prevenire i cambiamenti che rompono l'applicazione da raggiungere versioni di app incompatibili
• Gestisci diverse versioni di app Contemporaneamente senza logica complessa
• Aggiorna senza problemi a specifici segmenti di utenti

Perché la Versione 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 live update bundle alle versioni native di app, impedendo che JavaScript incompatibile fosse consegnato alle versioni native più vecchie di code.

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

• Controllo più granulare sulla corrispondenza delle versioni
• Strategie multiple (canali, semver, vincoli nativi)
• Migliore visibilità sulla distribuzione delle versioni
• API e CLI controllano insieme alla gestione del pannello

Questo approccio è particolarmente utile quando:

• Hai utenti su diverse versioni maggiori dell'app (ad esempio, v1.x, v2.x, v3.x)
• Hai bisogno di mantenere la compatibilità inversa mentre rilasci cambiamenti breaking
• Vuoi prevenire 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 abbinare gli utenti con aggiornamenti compatibili:

1. Restrizioni di Versione Nativa: Prevenire i pacchetti da essere consegnati a versioni native incompatibili
2. Routing per Canali: Inviare diverse versioni dell'applicazione a diversi canali di aggiornamento
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 Abbinamento di Versione

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]

Strategy 1: Routing della versione basato sul canale

Questo è il metodo consigliato per gestire i cambiamenti di versione e le aggiornamenti di versione principale. È 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 add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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

When gli utenti aprono l'app, si connettono automaticamente al loro canale designato in base ai defaultChannel nella loro installazione del bundle dell'app. Nessuna modifica del codice code richiesta!

Vantaggi

• Zero code modifiche - La routing del canale 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 breaking non raggiungono le versioni incompatibili

Strategia 2: Controlli di versioning semantico

Usa Capgo's funzionalità integrate controlli di versioning semantica per prevenire gli aggiornamenti oltre i confini delle versioni.

Disabilita Aggiornamento Automatico Tra Versioni Principali

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

Questa configurazione significa:

• Gli utenti con versione dell'app 1.2.3 riceveranno gli aggiornamenti fino a 1.9.9
• Utenti saranno NO ricezione della versione 2.0.0 automaticamente
• Preventa che i cambiamenti di base raggiungano le native più vecchie code
• La comparazione utilizza la linea di base nativa inviata 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 obbligatoria

Questa strategia funziona solo se segui. Semantic Versioning Required assicurati che i numeri di versione dei tuoi app siano in linea con 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 invii solo ai dispositivi con un binario nativo abbastanza nuovo.

Questo utilizza il canale ) più o--disable-auto-update metadata) plus --min-update-version or --auto-min-update-version on caricamento. Non c'è --native-version CLI flag.

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

Imposta una versione nativa minima all'upload

Quando si carica un bundle, passa la versione nativa più bassa che possa riceverlo:

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

O lascia che Capgo stabilisca il tetto dalla compatibilità del pacchetto nativo:

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) è sotto il bundle. min_update_version saltare l'aggiornamento. Solo i dispositivi su quella versione o successiva ricevono l'aggiornamento. Vedi Compatibility for --auto-min-update-version per

dettagli.

1. Sottosezione intitolata “Utilizzo”

   # 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 che rompono 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 dei canali

Nella dashboard Capgo:

1. Vai a Canali → Seleziona il tuo canale
2. Enable “Disable auto downgrade under native”
3. “Disabilita l'auto downgrade sotto nativo”

Ora tramite CLI:

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

Example

• Dispositivo dell'utente: Versione nativa 1.2.5
• Bundle 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 dalla store delle app
• È necessario assicurarsi 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.

Forzare 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 Dispositivo Override

Nella Capgo dashboard:

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

Testare Aggiornamenti

Usa le sovrapposizioni 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, 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. Rilascio Modifica Rilevante (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 Tutte 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. Monitora 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

Once v1 usage drops below 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 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 utente ha un'app con defaultChannel: 'v2' ma puoi sovrascrivere il dispositivo con 'beta' nel pannello di controllo, riceveranno aggiornamenti dal 'beta' canale.

Solo la UI di Override dispositivo elenca gli override impostati dal dashboard o da Public API. Chiamando setChannel() dalla app verifica il canale con il backend, quindi lo memorizza localmente sul dispositivo.

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

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

Controlla regolarmente la tua dashboard:

• Gli 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 AppFlowEcco come la Capgo gestisce la versione di destinazione.

Feature	Ionic AppFlow	Capgo
Routing basato sulla versione	Routing automatico sulla versione nativa	Routing automatico via defaultChannel + strategie multiple
Versioning semantico	Sostegno base	Sostegno avanzato con --disable-auto-update (maggiore/minore/patch)
Restrizioni sulla versione nativa	Configurazione manuale nel pannello di controllo di AppFlow	Costruito in --min-update-version / --auto-min-update-version con canali di metadati
Gestione del canale	Interfaccia Web + CLI	Interfaccia Web + CLI + API
Override del dispositivo	Gestione del dispositivo a livello limitata	Controllo completo tramite Dashboard/API
Prevenzione della discesa automatica	Sì	Sì via --no-downgrade
Mantenimento di più versioni	Gestione manuale della branca/canale	Automatizzato con precedenza del canale
Auto-hosting	No	Sì (controllo completo)
Analisi delle versioni	Basi	Metriche dettagliate per versione

AppFlow Parità e oltre

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

Risoluzione Problemi

Utenti che non ricevono Aggiornamenti

Controlla i seguenti punti:

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

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

2. Vincoli 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 impostazione

   npx @capgo/cli channel list

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

   • Dashboard → 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 pacchetto: Verifica che il pacchetto sia stato caricato sul canale inteso
3. Ispeziona la versione minima dell'aggiornamento: Conferma --min-update-version (o --auto-min-update-version: era impostato e il canale utilizza --disable-auto-update metadata

Modifiche Rilevanti che Affectano Versioni Antiche

1. Soluzione immediata: Sovrascrivi dispositivi affetti con pacchetto sicuro
   • Dashboard → Dispositivi → Selezione di massa → Imposta Versione
2. Soluzione a lungo termineCreare canali versionati e mantenere rami separati
3. PrevenzioneTestare sempre gli aggiornamenti su dispositivi rappresentativi prima della distribuzione

Migrazione da Ionic AppFlow

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

Carta concettuale

AppFlow Concept	Corrispettivo di Capgo	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 + controlli semver	Sono disponibili diverse strategie
Canale di Produzione	production nome del canale (o qualsiasi altro nome)	Nominazione flessibile
Deploy con Git	Caricamento del pacchetto CLI dalla branca	Lo stesso workflow
Corrispondenza di versione automatica	defaultChannel + vincoli di versione	Rafforzato con strategie multiple

Differenze chiave per gli utenti di AppFlow

1. Piu Controllo: Capgo offre diverse strategie (canali, semver, versione nativa) che possono essere combinate
2. Visibilità MigliorataLa 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. Set defaultChannel Inizia capacitor.config.ts per ogni versione maggiore
3. Configura le regole semver Se desideri il blocco automatico ai confini delle versioni
4. Carica bundle specifici per versione utilizzando --min-update-version (il canale deve utilizzare la strategia di metadati)
5. Monitora la distribuzione delle versioni in dashboard Capgo

Guida di Migrazione Completa

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

Modelli avanzati

Esecuzione graduale di una 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 })
  }
}

Somma

Capgo offre 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 tra confini di versione maggiore/minore/patch
3. Restrizioni native di versione: Richiedere la versione minima nativa per i pacchetti
4. Prevenzione del downgrade automatico: Mai consegnare pacchetti più vecchi alle versioni native più nuove
5. Override dispositivo: Controllo manuale per test e targeting

Combinando queste strategie, puoi raggiungere la consegna di aggiornamenti automatici con AppFlow 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 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 native di versione

Continua da qui: Version Targeting

Se stai utilizzando Target Versionamento per pianificare la routing del canale 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 di Beta per il workflow del prodotto in Soluzione di Test di Beta, e Soluzione di Targeting della Versione per il workflow del prodotto in Soluzione di Targeting della Versione.