Capgo’s version names can feel backward at first: version_build è la baseline dell'app nativa, mentre version_name traccia il bundle sul dispositivo. Se hai ben chiara la distinzione, puoi verificare perché un dispositivo riceverà o meno un aggiornamento OTA prima del rilascio.
Abbiamo analizzato le pagine di troubleshooting di 5 piattaforme di live update, inclusa la nostra, e abbiamo scoperto che la nostra documentazione elenca 7 codici con nome per il mismatch di version_build, contro 5, 2, 2 e 0 delle altre quattro. Più codici con nome significano meno tentativi a indovinare quando compare un mismatch di version_build.
Indice dei contenuti
- Passaggio 1: Individua version_build e version_name in Capgo
- Passaggio 2: Identifica la baseline nativa e il bundle scaricato
- Passaggio 3: Controlla da dove proviene la versione della tua app nativa
- Passaggio 4: Imposta e verifica la versione del bundle che Capgo riceve
- Passaggio 5: Testa l'idoneità del canale prima di rilasciare un update
- Passaggio 6: Diagnostica i mismatch di versione e rendi ripetibili le release
- FAQ
- Conclusione
Passaggio 1: Individua version_build e version_name in Capgo
Inizia trattandoli come due fatti distinti relativi a un'installazione dell'app. version_build indica a Capgo quale versione dell'app nativa è sul dispositivo. version_name indica a Capgo quale bundle JavaScript ha scaricato il dispositivo. Possono avere valori diversi, ed è spesso normale.
Nel modello di versioning di Capgo, la versione nativa è il punto di riferimento per l'idoneità agli aggiornamenti. Capgo confronta il bundle assegnato a un canale con quella baseline nativa. La versione del bundle installato sul dispositivo aiuta a identificare la sua web code attuale, ma non sostituisce la baseline nativa nelle regole di versione del canale.
Cerca il dispositivo nella pagina Dispositivi della console Capgo e annota entrambi i valori prima di fare troubleshooting. Poi confrontali con il bundle target del canale. Il Regole del canale Capgo spiegano come la versione target di un canale viene verificata rispetto a version_build.
| Valore | Cosa rappresenta | Usalo per rispondere a | Fonte tipica |
|---|---|---|---|
version_build |
Baseline dell'app nativa inviata a Capgo | Questa app nativa può ricevere il bundle target del canale? | Versione dell'app nativa o valore di configurazione esplicito Capacitor |
version_name |
Bundle JavaScript attualmente scaricato | Quale versione del bundle è installata ora? | Versione del bundle risolta durante l'upload |
| Target del canale | Bundle assegnato al canale del dispositivo | Quale versione sta controllando Capgo per un aggiornamento? | Assegnazione del canale corrente |
Mantieni i tre valori in colonne separate in una release note o in un report di test. Se il team scrive un generico “app version”, è facile confrontare la coppia sbagliata. Per l'idoneità, confronta il bundle target con version_build. Per il web code installato, verifica version_name.
La nomenclatura di Capgo può sembrare diversa dalle convenzioni Android, dove i team usano spesso “build” per indicare un numero di build incrementale. Qui, leggi il campo in base al suo ruolo di Capgo, non per ciò che suggerisce il nome. Questa piccola abitudine previene molta confusione in fase di rilascio.
Passaggio 2: Identifica la baseline nativa e il bundle scaricato
Prima di modificare un valore di versione, identifica quale code è nativo e quale code viene consegnato come bundle. L'app nativa è il binario iOS o Android installato. Il bundle contiene gli asset web che un'app Capacitor può ricevere tramite un aggiornamento OTA.
Immagina un'app nativa rilasciata con baseline 1.2.3. Una successiva correzione web viene caricata come bundle 1.2.4. Capgo verifica se il bundle target del canale è consentito per la baseline nativa 1.2.3. Se è idoneo, il dispositivo può scaricare quel bundle. Dopo l'installazione, version_name riflette il bundle ora presente sul dispositivo. La baseline nativa rimane legata al binario installato.
Questa differenza conta quando un utente ha una build app-store più vecchia ma un bundle web più recente. Il bundle può cambiare senza sostituire il binario nativo, ma un aggiornamento OTA non può aggiungere un code nativo che non era incluso nell'app. Se una modifica richiede un nuovo plugin o un'impostazione nativa, pianifica una build nativa invece di considerare l'upload del bundle come un sostituto.

Usa questo controllo rapido quando i valori sembrano fuori sincrono:
- Conferma quale binario nativo è installato sul dispositivo di test.
- Trova il valore di versione che Capgo riceve come baseline nativa.
- Controlla la versione del bundle assegnata al canale del dispositivo.
- Registra la versione del bundle installata separatamente da entrambe.
Non dedurre la baseline nativa da package.json a meno che il tuo processo di build non copi deliberatamente quel valore nella versione nativa o nella configurazione Capgo. La versione di un progetto JavaScript e quella di un'app installata dagli store possono divergere. La fonte corretta è quella che la tua app invia effettivamente a Capgo.
Una volta identificati la baseline e il bundle corrente, il passo successivo è ricondurre ogni valore al suo file sorgente. È qui che tendono a emergere le differenze tra le piattaforme.
Passaggio 3: Controlla da dove proviene la versione della tua app nativa
Per un risultato affidabile version_build, individua la versione nativa riportata dalla tua app Capacitor. La documentazione sulle versioni di Capgo descrive chiavi sorgente diverse per iOS e Android, usando poi il valore nativo risultante come baseline per il confronto OTA.
Su iOS
Verifica CFBundleShortVersionString nella scheda dell'app Info.plist. In most Xcode projects that key is set to $(MARKETING_VERSION), quindi il valore che modifichi effettivamente è la Marketing Version del target. Verifica il valore nell'app compilata, non solo in un template o in un file che la tua build potrebbe sovrascrivere.
Quando un team aggiorna il progetto Xcode ma non il valore che raggiunge l'app, la visualizzazione locale del progetto può sembrare corretta, mentre il binario installato riporta un altro valore. Confronta la versione nell'app nativa generata con il valore previsto dal tuo processo di release.
Su Android
Verifica defaultConfig.versionName nella configurazione Gradle dell'app Android. Quel nome di versione nativo viene usato nel confronto OTA di Capgo. Non confonderlo con un code di build Android o con la versione di un pacchetto JavaScript non correlato. Per questo controllo, la domanda importante è quale nome di versione invii l'app nativa.
Una policy di versione condivisa può aiutare entrambe le piattaforme a restare allineate, ma non dare per scontato che abbiano già un'unica fonte. iOS e Android potrebbero avere file, step di build o tempi di rilascio separati. Confronta i valori finali durante il controllo del rilascio, soprattutto se una piattaforma ha un calendario di rollout sugli store diverso.
Alcune app impostano esplicitamente la versione nativa in capacitor.config.ts tramite il valore version della configurazione dell'updater. Il Capgo Semver Tester descrive questa baseline nativa come un valore che può derivare dalla configurazione o dai metadati dell'app nativa. Se la tua app sovrascrive i metadati nativi, documenta questa scelta in modo che nessuno si aspetti che la versione dello store sia la fonte.
Per ogni piattaforma, annota il file sorgente, il valore risolto e la build che lo contiene. Così è più facile rintracciare un eventuale mismatch dopo un rilascio, quando il repository potrebbe già contenere una versione più recente di quella installata sul dispositivo di un tester.
Cambia solo la sorgente che la tua build legge effettivamente. Modificare un file obsoleto può far sembrare completa una revisione di code, lasciando però invariata la versione nativa pacchettizzata.
Passaggio 4: Imposta e verifica la versione del bundle che Capgo riceve
La versione del bundle descrive l'aggiornamento JavaScript, non il binario nativo installato. Capgo può prendere quella versione dal version campo in package.json quando non fornisci una versione del bundle esplicita. L'opzione di CLI --bundle può impostare la versione inviata durante l'upload.
Scegli un unico percorso e rendilo chiaro nel tuo processo di rilascio. Se package.json è la sorgente, incrementa quel campo prima dell'upload. Se la CI passa una versione del bundle tramite CLI, fai in modo che il job stampi la versione risolta nei log di rilascio. Un mix silenzioso dei due percorsi rende più difficile capire perché il canale ha ricevuto un certo valore.
Usa il semantic versioning nel consueto major.minor.patch formato, come ad esempio 1.2.3Le strategie dei canali Capgo utilizzano le parti di quella versione per decidere se un bundle di destinazione è compatibile con una baseline native. Un suffisso pre-release come -beta.1 può aiutare a etichettare i build specifici per canale, ma mantieni la versione parseabile e coerente tra i tuoi strumenti di rilascio.
Valuta bene l'incremento prima di pubblicare:
- Usa un incremento di patch per un fix web compatibile nella stessa linea di rilascio.
- Usa un incremento minore quando la modifica appartiene a una nuova linea di funzionalità compatibile.
- Usa un incremento maggiore quando cambia il confine di compatibilità e le versioni native code precedenti potrebbero non supportare il bundle.
Questi etichette sono una convenzione di team, non un modo per aggiungere capacità native tramite OTA. Un numero di versione non può dimostrare che un bundle sia sicuro per un'app nativa. Mantieni le decisioni di compatibilità effettive legate al code e alle dipendenze nel binario.
Prima dell'upload, confronta la versione del pacchetto o il valore CLI con la versione mostrata per il bundle dopo l'upload. Ispeziona anche il canale che lo servirà. Caricare un bundle correttamente denominato su un canale non previsto può comunque portare a risultati di test errati.
Stringhe non valide o incoerenti meritano una verifica, non un'ipotesi. Mantieni un valore di rilascio noto e funzionante, correggi la sorgente e testa la versione risolta prima di promuoverla.
Il Riferimento comandi Capgo CLI è utile quando integri l'upload in uno script, perché la versione del bundle fa parte degli input del comando di release.
Passaggio 5: Testa l'idoneità del canale prima di rilasciare un update
L'idoneità al canale è un confronto, non un'ipotesi basata su quale bundle sembri più recente. Capgo confronta il bundle di destinazione del canale con la baseline nativa inviata come version_build. Il bundle attualmente scaricato, riportato come version_name, non è la baseline per quelle regole di canale.
Per esempio, supponiamo che un'app nativa installata riporti 1.2.3, mentre il suo bundle attuale è 1.2.4. Se un canale punta a 1.2.5, confronta il target con la baseline nativa 1.2.3, non solo con il bundle attuale 1.2.4. I target consentiti dipendono dalla strategia di update del canale.
Capgo documenta strategie come major e minor che limitano gli update rispetto alla baseline nativa. Con una strategia major, può essere bloccato un target con una versione major superiore. Con una strategia minor, può essere bloccato un target che cambia la linea major o minor della baseline. Controlla la strategia configurata invece di dare per scontato che ogni bundle che sembra più recente venga accettato.

Testa la combinazione esatta che intendi rilasciare:
- Installa la build nativa che rappresenta gli utenti che vuoi raggiungere.
- Conferma la baseline nativa inviata a Capgo.
- Assegna il dispositivo di test al canale desiderato.
- Controlla il target del canale e la sua strategia di versione.
- Richiedi un aggiornamento e conferma il risultato sul dispositivo.
Esegui lo stesso controllo su un'altra baseline nativa se la tua base utenti ha più di una versione dello store in uso. Un bundle che funziona su una build recente potrebbe essere bloccato su un binario più vecchio, e potrebbe essere proprio la regola di sicurezza prevista.
Per i rilasci più ampi, parti da un canale di test o da un rollout limitato. Monitora eventuali risultati di idoneità inattesi prima di ampliare il pubblico. Il modello di canali di Capgo permette ai team di indirizzare i bundle tramite canali di rilascio; tieni ben chiari il target e la linea nativa prevista di ogni canale nelle release notes.
Se un dispositivo di test non si aggiorna, controlla l'assegnazione del canale e i valori di versione prima di fare un nuovo upload. Pubblicare ripetutamente lo stesso bundle non risolverà un mismatch della baseline.
Passaggio 6: Diagnostica i mismatch di versione e rendi ripetibili le release
Quando i valori non corrispondono a quanto ti aspetti, verificali in ordine. Prima conferma la versione dell'app nativa sul dispositivo. Poi controlla se un override di configurazione cambia la baseline. Quindi confronta la versione del bundle ricevuta da Capgo con il target del canale. Questa sequenza distingue un valore sorgente errato da una regola del canale che funziona come configurata.
Le cause comuni includono l'incremento package.json mentre la versione nativa rimane invariata, facendo la build di una piattaforma da un branch di release diverso e testando un dispositivo assegnato a un altro channel. Un'altra fonte di confusione è chiamare ogni numero una “build version”. Annota quale valore è nativo, quale è il bundle caricato e quale è quello attualmente installato.
Per la CI/CD, rendi espliciti gli input di versione. Fai in modo che la pipeline legga la versione di release prevista da una sorgente controllata, poi passala al comando di upload o aggiorna il campo del package prima dello step di upload. Registra la baseline nativa risolta e il target del bundle nell'output del job. Evita di affidarti allo stato locale di uno sviluppatore che il build server non può vedere.
Usa un release gate che fallisca se manca una versione richiesta o se ha un formato che il tuo team non accetta. Poi esegui un upload di test sul channel corretto prima della promozione. Capgo supporta un flusso di deployment basato su CLI, così i team possono integrare l'upload del bundle nel job CI/CD esistente e mantenere un log dei comandi visibile.
Non confondere questi valori con la versione del motore WebView di Android. Il nostro @capgo/capacitor-webview-version-checker plugin controlla se il motore WebView di un dispositivo è obsoleto e può mostrare un prompt di aggiornamento nativo. È una questione separata da version_build e version_name, quindi non sostituisce mai il controllo della baseline nativa e del bundle target del channel.
Quando si migra da uno schema legacy, non rinominare tutti i valori esistenti in un solo passaggio. Mappa prima la vecchia versione nativa sulla baseline nativa. Poi mappa la release web caricata sulla versione del bundle. Testa build rappresentative delle app esistenti rispetto alla strategia del canale prima di indirizzare gli utenti a quella strategia.
Mantieni un breve registro di rilascio con il commit sorgente, la versione nativa, la versione del bundle caricato, il canale e il risultato del test. Se un rilascio deve essere messo in pausa o sottoposto a rollback, quel registro aiuta il team a identificare quale bundle è andato dove. Rende anche il prossimo deployment ripetibile, invece di dipendere da qualcuno che si ricordi quale file è stato modificato.
FAQ
Qual è la differenza tra version_build e version_name in Capgo?
version_build è la baseline dell'app nativa, mentre version_name è la versione corrente del bundle scaricato. Capgo usa la baseline nativa quando verifica l'idoneità del bundle target di un canale. Mantieni i due valori separati nei log e nelle note di rilascio, così puoi distinguere quale app nativa è installata e quale bundle web ha.
version_name controlla se un aggiornamento OTA è consentito?
No, le strategie di versione dei canali di Capgo confrontano il bundle target con version_build, la baseline nativa. version_name identifica il bundle attualmente scaricato. Se un dispositivo non riceve un aggiornamento, verifica il suo baseline, il target del canale e la strategia configurata prima di modificare il valore del bundle corrente.
Da dove Capgo ottiene la versione nativa?
Su iOS, Capgo legge CFBundleShortVersionString, che Xcode solitamente compila da MARKETING_VERSION. Su Android, la versione nativa proviene da defaultConfig.versionName. Una versione esplicita dell'updater nella configurazione di Capacitor può modificare il valore inviato dalla tua app, quindi verifica l'app compilata.
Da dove Capgo ottiene la versione del bundle?
Capgo può utilizzare il version campo in package.json quando non specifichi una versione del bundle esplicita. Puoi anche fornire la versione tramite i CLI --bundle opzione. Scegli una sola fonte chiara per il tuo workflow di release, quindi verifica la versione Capgo ricevuta dopo l'upload.
Conclusione
Usa version_build per la baseline nativa e version_name per il bundle installato. Prima del prossimo rollout, verifica entrambi i valori su un dispositivo di test e confronta il target del channel con la baseline. Questo singolo controllo può individuare un mismatch di versione prima che raggiunga un pubblico più ampio.