Capgo version_build vs version_name: Passaggi di configurazione

Capgoi nomi delle versioni possono sembrare invertiti all'inizio: version_build è la baseline dell'app nativa, mentre version_name traccia il bundle sul dispositivo. Capire la distinzione ti permette di 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 di mismatch per version_build, contro i 5, 2, 2 e 0 delle altre quattro. Più codici specifici significano meno incertezze 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.

Cerca 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 del canale Capgo spiegano come la versione target di un canale venga verificata rispetto a version_build.

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'idoneità, 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 per 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 cambiare 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 native baseline 1.2.3. Se è idoneo, il dispositivo può scaricare quel bundle. Dopo l'installazione, version_name riflette il bundle ora presente sul dispositivo. La native baseline rimane legata al binario installato.

Questa differenza è cruciale quando un utente ha una build degli 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 code nativi che non erano inclusi nell'app. Se una modifica richiede un nuovo plugin o un'impostazione nativa, pianifica una Native Build invece di considerare un bundle upload 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 della versione che Capgo riceve come native baseline.
• Controlla la versione del bundle assegnata al canale del dispositivo.
• Registra la versione del bundle installato separatamente da entrambe.

Non dedurre la native baseline 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 riusciti a identificare la baseline e il bundle corrente, il passo successivo è risalire a ogni valore dal 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 diverse chiavi sorgente per iOS e Android, usando poi il valore nativo risultante come baseline per il confronto OTA.

Su iOS

Controlla CFBundleShortVersionString in the app’s 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 altro. Confronta la versione nell'app nativa generata con il valore previsto dal tuo processo di release.

Su Android

Controlla defaultConfig.versionName nella configurazione Gradle dell'app Android. Quel nome versione nativo viene utilizzato nel confronto OTA di Capgo. Non confonderlo con un code di Android o con una versione di un pacchetto JavaScript non correlato. Per questo controllo, la domanda fondamentale è quale nome versione invii l'app nativa.

Una policy di versione condivisa può aiutare entrambe le piattaforme a rimanere allineate, ma non dare per scontato che abbiano già un'unica fonte. iOS e Android potrebbero avere file, passaggi di build o tempi di rilascio separati. Confronta i valori finali durante il controllo del rilascio, specialmente se una piattaforma ha un programma di rollout sullo store differente.

Alcune app impostano esplicitamente la versione nativa in capacitor.config.ts tramite il valore version nella configurazione dell'updater. Il Capgo Semver Tester descrive questa baseline nativa come un valore che può provenire 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 principale.

Per ogni piattaforma, annota il file sorgente, il valore risolto e la build che lo contiene. Questo rende un eventuale mismatch più facile da tracciare dopo un rilascio, quando il repository potrebbe già contenere una versione più recente rispetto a 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ò prelevare tale versione dal version campo in package.json quando non viene fornita una versione esplicita del bundle. Le CLI --bundle l'opzione permette di 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 di entrambi i percorsi rende difficile capire perché il canale abbia ricevuto un determinato valore.

Usa il semantic versioning nel consueto major.minor.patch formato, come ad esempio 1.2.3. Le strategie dei canali di Capgo usano le parti di quella versione per decidere se un bundle target è compatibile con una baseline nativa. 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 cambio di patch per un fix web compatibile all'interno della stessa release line.
• Usa un cambio minor quando la modifica appartiene a una nuova linea di funzionalità 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à reali legate a 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 non previsto può comunque portare a risultati di test errati.

Stringhe non valide o incoerenti richiedono un controllo, non un'ipotesi. Mantieni un valore di release noto e funzionante, 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 channel è un confronto, non un'ipotesi basata su quale bundle sembri più recente. Capgo verifica il bundle target del channel rispetto alla baseline nativa inviata come version_build. Il bundle scaricato attualmente, riportato come version_name, non è la baseline per le regole di quel channel.

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 più recente venga accettato.

Testa l'esatta combinazione che intendi rilasciare:

1. Installa il Native Build che rappresenta gli utenti che vuoi colpire.
2. Conferma la baseline nativa inviata a Capgo.
3. Assegna il dispositivo di test al canale desiderato.
4. Controlla il target del canale e la sua strategia di versione.
5. 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 dei test. Se una release deve essere sospesa o riportata indietro, quel registro aiuta il team a capire 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 baseline dell'app nativa, mentre version_name è la bundle version attualmente scaricata. Capgo usa la native baseline quando controlla l'idoneità del bundle target 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 bundle target 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 del bundle corrente.

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 prende Capgo la versione del bundle?

Capgo può usare il campo version 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 attendibile 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 canale target con la baseline. Un semplice controllo può prevenire un mismatch di versione prima che raggiunga un pubblico più ampio.