CapgoI nomi delle versioni possono sembrare invertiti all'inizio: 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 versionamento di Capgo, la versione nativa è il punto di riferimento per l'idoneità agli update. Capgo confronta il bundle assegnato a un canale con tale baseline nativa. La versione del bundle installato sul dispositivo aiuta a identificare la sua attuale code web, ma non sostituisce la baseline nativa nelle regole di versione del canale.
Controlla il dispositivo nella pagina Devices della console Capgo e annota entrambi i valori prima di procedere con il troubleshooting. Poi confrontali con il bundle target del canale. Il/La Regole dei canali Capgo spiega come viene verificata la versione target di un canale rispetto a version_build.
| Valore | Cosa rappresenta | Usalo per rispondere | Fonte tipica |
|---|---|---|---|
version_build |
Baseline app nativa inviata a Capgo | Questa app nativa può ricevere il bundle target del canale? | Versione dell'app nativa o valore di configurazione Capacitor esplicito |
version_name |
Bundle JavaScript scaricato attualmente | Quale versione del bundle è installata ora? | Versione del bundle risolta durante l'upload |
| Target del canale | Bundle assegnato al canale del dispositivo | Per quale versione Capgo sta cercando un aggiornamento? | Assegnazione canale attuale |
Mantieni i tre valori in colonne separate nelle release note o nei report di test. Se il team scrive un generico "versione app", è facile confrontare la coppia sbagliata. Per l'eligibility, confronta il bundle target con version_build. Per il code web installato, controlla version_name.
Il naming di Capgo può sembrare diverso 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 Capgo, non in base a ciò che suggerisce il nome. Questa piccola abitudine evita molta confusione durante il 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 la 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 ora il bundle presente sul dispositivo. La baseline nativa rimane legata al binario installato.
Questa differenza è cruciale quando un utente ha una vecchia build dell'app store ma un bundle web più recente. Il bundle può cambiare senza sostituire il binario nativo, ma un aggiornamento OTA non può aggiungere code nativi che non erano inclusi nell'app. Se una modifica richiede un nuovo plugin o un'impostazione nativa, pianifica un Native Build invece di considerare l'upload di un 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 cambio minor quando la modifica appartiene a una nuova linea di feature compatibili.
- Usa un cambio major quando cambia il limite di compatibilità e i vecchi code nativi potrebbero non supportare il bundle.
Questi label sono una convenzione del team, non un modo per aggiungere capacità native tramite OTA. Un numero di versione non può garantire che un bundle sia sicuro per un'app nativa. Mantieni le decisioni di compatibilità 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 channel che lo servirà. Caricare un bundle con il nome corretto su un channel errato può comunque portare a risultati di test sbagliati.
Stringhe non valide o inconsistenti richiedono un controllo, non un'ipotesi. Mantieni un valore di release noto e sicuro, correggi la sorgente e testa la versione risolta prima di promuoverla.
Il Riferimento al comando Capgo CLI è utile quando integri l'upload in uno script, poiché 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à del canale è un confronto, non una stima basata su quale bundle sembri più recente. Capgo confronta il bundle target del canale con il baseline nativo inviato come version_build. Il bundle attualmente scaricato, riportato come version_name, non è il baseline per le regole di quel 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 migri da uno schema legacy, non rinominare tutti i valori esistenti in un colpo solo. Mappa prima la vecchia versione nativa con la native baseline. Poi mappa la web release caricata con la bundle version. Testa build esistenti rappresentative rispetto alla strategia del canale prima di indirizzare gli utenti.
Mantieni un registro delle release con commit sorgente, versione nativa, bundle version caricata, canale e risultato del test. Se una release deve essere sospesa o sottoposta a rollback, quel registro aiuta il team a identificare quale bundle è stato inviato dove. Rende inoltre il prossimo deployment ripetibile, senza dipendere dalla memoria di qualcuno su quale file sia stato cambiato.
FAQ
Qual è la differenza tra version_build e version_name in Capgo?
version_build è la native app baseline, mentre version_name è la bundle version attualmente scaricata. Capgo usa la native baseline quando controlla l'idoneità del target bundle di un canale. Mantieni i due valori separati nei log e nelle release note per distinguere quale app nativa è installata e quale web bundle ha.
version_name controlla se un aggiornamento OTA è consentito?
No, le strategie di versione dei canali di Capgo confrontano il target bundle con version_build, la native baseline. version_name identifica la bundle version attualmente scaricata. Se un dispositivo non riceve un aggiornamento, controlla la sua baseline, il target del canale e la strategia configurata prima di modificare il valore della bundle version attuale.
Da dove ottiene Capgo la versione nativa?
Su iOS, Capgo legge CFBundleShortVersionString, che di solito Xcode compila da MARKETING_VERSION. Su Android, la versione nativa proviene da defaultConfig.versionName. Una versione updater esplicita nella configurazione di Capacitor può cambiare il valore inviato dalla tua app, quindi verifica l'app buildata.
Da dove recupera Capgo la versione del bundle?
Capgo può usare la version campo in package.json quando non viene passata una versione del bundle esplicita. Puoi anche fornire la versione con i CLI --bundle Scegli una singola fonte univoca per il tuo workflow di rilascio, 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 canale con la baseline. Un semplice controllo può prevenire un mismatch di versione prima che raggiunga un pubblico più ampio.