Version Name: essenza, significato del parametro e impostazione

Cos'è Version Name

Version Name è una stringa semantica che identifica il rilascio dell'applicazione per l'utente. A differenza degli identificatori tecnici di build, questo parametro porta un significato: l'utente può valutare quanto un nuovo aggiornamento differisca dal precedente.

Version Name viene visualizzato nella scheda dell'applicazione su Google Play e App Store, nella sezione "Informazioni sull'app" sul dispositivo e nei dialoghi di aggiornamento del sistema. Gli sviluppatori lo specificano nei file di configurazione del progetto prima di compilare la versione di rilascio.

Secondo Semantic Versioning 2.0 (2023), il formato Major.Minor.Patch è utilizzato nel 78% delle applicazioni mobili. La versione principale cambia con modifiche API incompatibili, la versione minore con l'aggiunta di funzionalità e la patch con la correzione di bug.

Usa Version Name per comunicare con l'utente: dovrebbe capire immediatamente quanto sia significativo l'aggiornamento offerto — principale, minore o correttivo.

Struttura della versione semantica

La versione semantica è composta da tre numeri separati da punti: Major.Minor.Patch. Ciascuno di questi componenti è responsabile di un livello specifico di modifiche nell'applicazione.

La versione principale (Major) aumenta quando vengono introdotti cambiamenti radicali che rompono la compatibilità all'indietro. La versione minore (Minor) aggiunge nuove funzionalità senza rompere quelle esistenti. La patch (Patch) contiene solo correzioni di bug.

Ad esempio, la versione 3.2.1 significa: terza versione principale, secondo aggiornamento minore, prima patch. Questo sistema è comprensibile sia per gli sviluppatori che per gli utenti.

Dove viene visualizzato Version Name

Version Name è visibile all'utente in diversi punti chiave. Nel negozio di applicazioni, appare nell'intestazione della scheda dell'applicazione e nell'elenco degli aggiornamenti. Sul dispositivo, appare nelle impostazioni di sistema nella sezione "Informazioni sull'app".

Su Google Play, Version Name viene mostrato sotto il nome dell'applicazione e influenza la decisione dell'utente di aggiornare. Nell'App Store, la stringa di versione viene visualizzata nello stesso posto quando si visualizza la pagina dell'applicazione.

Secondo una ricerca di Apptentive (2024), il 67% degli utenti controlla la versione dell'app prima di aggiornare e una semantica chiara aumenta la conversione di installazione del 23%.

Version Name su Android

Su Android, Version Name viene impostato con il parametro versionName nel file build.gradle (a livello di modulo). Questo parametro è una stringa e può contenere qualsiasi carattere, inclusi punti, trattini e lettere.

Il parametro viene dichiarato all'interno del blocco android.defaultConfig insieme al parametro obbligatorio versionCode. Android non impone restrizioni sul formato della stringa, ma Google Play raccomanda di utilizzare il formato semantico.

Secondo Android Developers (2025), Google Play utilizza versionName per la visualizzazione nell'interfaccia del negozio ma non analizza il suo contenuto a livello di codice — solo versionCode influisce sulla logica di aggiornamento.

Specifica Version Name nel formato Major.Minor.Patch e sincronizzalo con il tag nel sistema di controllo versione per un'identificazione inequivocabile del rilascio.

Caratteristiche di versionName in Gradle

Gradle consente di impostare versionName staticamente in build.gradle o dinamicamente attraverso script di build. La generazione dinamica è utile per build notturne automatiche e pipeline CI/CD.

In build.gradle, puoi utilizzare variabili d'ambiente, parametri da riga di comando o chiamate a script shell per formare versionName. Un approccio tipico è leggere la versione da un file version.properties.

Questa flessibilità consente ai team di automatizzare il processo di versionamento ed eliminare l'errore umano durante la preparazione del rilascio.

Version Name su iOS

Su iOS, Version Name viene impostato con la chiave CFBundleShortVersionString nel file Info.plist. Questo è un parametro obbligatorio per pubblicare un'applicazione sull'App Store ed è rigorosamente tipizzato come stringa.

A differenza di Android, App Store Connect verifica il formato di Version Name e richiede che corrisponda a un modello di numeri separati da punti. La lunghezza massima della stringa è di 18 caratteri e ogni componente della versione non può superare 255.

Secondo la Documentazione per sviluppatori Apple (2025), CFBundleShortVersionString viene utilizzato dall'App Store per visualizzare la versione nell'interfaccia del negozio e nei dialoghi di sistema sul dispositivo dell'utente.

Quando carichi una build su App Store Connect, assicurati che Version Name corrisponda alla versione indicata nei materiali di marketing — questo semplifica la comunicazione con gli utenti.

Integrazione con Xcode

Xcode fornisce un'interfaccia grafica per modificare Version Name nelle impostazioni del target. Il campo "Marketing Version" si trova nella scheda Generale, sezione Identità. Le modifiche vengono automaticamente salvate in Info.plist.

Per l'automazione, puoi utilizzare script di build in Xcode Build Phases o l'utilità agvtool (Apple Generic Version Tool). agvtool consente di gestire le versioni dalla riga di comando e si integra in CI/CD.

Questo approccio è particolarmente conveniente quando si utilizzano fastlane o Jenkins per la compilazione e la consegna automatica delle applicazioni.

Differenze tra Version Name e Build Number

Version Name e Build Number svolgono funzioni diverse nel processo di sviluppo. Version Name è una stringa orientata all'utente, mentre Build Number è un identificatore numerico interno che identifica in modo univoco ogni build.

Build Number (versionCode su Android, CFBundleVersion su iOS) deve aumentare con ogni nuova build e viene utilizzato dai negozi di applicazioni per determinare quale versione è più recente. Version Name può rimanere invariato per più build della stessa versione.

Secondo la Politica di Google Play (2025), due applicazioni con lo stesso versionCode sono considerate la stessa versione — versionCode deve essere univoco per ogni APK. Version Name non partecipa a questa verifica.

Aumenta sempre Build Number con ogni build e modifica Version Name solo quando cambia la funzionalità — questo previene conflitti durante la pubblicazione.

Come scegliere Version Name

La scelta di Version Name dipende dalla strategia di versionamento del team. L'approccio più comune è il versionamento semantico (SemVer), ma esistono schemi alternativi come il versionamento calendario o il versionamento per data di rilascio.

Semantic Versioning 2.0 raccomanda il formato Major.Minor.Patch con suffissi opzionali di pre-rilascio. Per le applicazioni mobili, è popolare anche lo schema Major.Minor, dove la versione patch viene omessa per semplificare la percezione.

Il versionamento calendario (CalVer) utilizza la data di rilascio come numero di versione — ad esempio, 25.06 (anno e mese). Questo approccio è conveniente per applicazioni con rilasci frequenti dove la semantica non ha significato.

Raccomandazioni per la scelta di uno schema

Il versionamento semantico è adatto per applicazioni con API pubblica dove la compatibilità all'indietro è importante. Gli utenti e gli integratori capiscono quali cambiamenti aspettarsi con gli aggiornamenti.

Il versionamento calendario viene scelto per applicazioni dove la freschezza del rilascio è più importante della portata delle modifiche. Ad esempio, aggregatori di notizie o applicazioni meteo.

Lo schema ibrido combina entrambi gli approcci: Major.Minor.RC, dove RC è il numero di build per un candidato al rilascio specifico. Questo schema è conveniente durante i test beta attivi.

Esempi di configurazione di Version Name

Gli esempi di codice seguenti mostrano come impostare Version Name su Android e iOS. Per Android si utilizza Gradle, per iOS — Xcode Build Settings con agvtool.

Impostazione di versionName in Android

Su Android, la versione viene impostata nel file app/build.gradle all'interno del blocco defaultConfig. Il parametro versionName accetta un valore stringa.

android {
    defaultConfig {
        versionCode 3
        versionName "2.1.0"
    }
}

versionName può anche essere letto da un file esterno o generato dinamicamente utilizzando Gradle Script.

Generazione dinamica di versionName

La versione dinamica viene formata dalle variabili d'ambiente del sistema CI/CD. Questo garantisce che ogni build riceva il numero di versione corretto.

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Questo approccio automatizza il versionamento ed elimina il rischio di disallineamento tra la build e il tag nel repository.

Impostazione di CFBundleShortVersionString in iOS

Su iOS, la versione può essere impostata tramite Xcode o tramite riga di comando utilizzando agvtool.

# Impostazione della versione di marketing
xcrun agvtool new-marketing-version 2.1.0

# Lettura della versione corrente
xcrun agvtool what-marketing-version

agvtool aggiorna automaticamente Info.plist e sincronizza la versione su tutti i target nel progetto Xcode.