Marketing Version: cos'è, differenza da Build Number e configurazione

Cos'è Marketing Version

Marketing Version è una stringa semantica che rappresenta la versione dell'applicazione per l'utente finale. Su iOS viene impostata tramite la chiave CFBundleShortVersionString, su Android tramite versionName.

Il termine “Marketing Version” viene ufficialmente utilizzato in Xcode: nell'interfaccia delle impostazioni del target, il campo si chiama “Marketing Version” e in Info.plist corrisponde a CFBundleShortVersionString. Su Android l'equivalente è versionName, sebbene il termine sia meno utilizzato.

Secondo la Documentazione Apple Developer (2025), Marketing Version deve essere composta al massimo da tre numeri separati da punti, senza spazi o caratteri speciali. Ogni numero non deve superare 255.

Scegli la tua Marketing Version in modo che rifletta l'importanza delle modifiche: versioni major per cambiamenti fondamentali, versioni minor per nuove funzionalità.

Differenza dal Build Number interno

Marketing Version differisce fondamentalmente da Build Number nello scopo: il primo informa l'utente, il secondo identifica il build per lo store. Build Number può aumentare senza modificare Marketing Version.

Ad esempio, durante la correzione di un bug critico in una versione pubblicata, il team può ricompilare l'applicazione con la stessa Marketing Version (1.2.0) ma con un Build Number più alto (da 15 a 16). L'utente vedrà la stessa versione, ma lo store saprà che il build è più recente.

Questa flessibilità consente agli sviluppatori di pubblicare correzioni senza informare gli utenti di un cambio di versione.

Dove viene visualizzata Marketing Version

Marketing Version appare in diversi punti chiave dell'interazione dell'utente con l'applicazione. Nello store di app, è visibile nella scheda dell'app, nella descrizione dell'aggiornamento e nella cronologia delle versioni.

Sul dispositivo, Marketing Version viene mostrata nelle impostazioni di sistema (sezione “Informazioni” o “App”), nei dialoghi di aggiornamento tramite App Store o Google Play, e all'interno dell'app stessa nella schermata “Informazioni”.

Una Marketing Version chiara aiuta gli utenti a valutare l'aggiornamento della versione installata e a decidere se eseguire l'aggiornamento.

Marketing Version su iOS

Su iOS, Marketing Version viene impostata in Xcode tramite il campo “Marketing Version” nella scheda General delle impostazioni del target. Il valore viene salvato in Info.plist come CFBundleShortVersionString.

Il formato della versione è strettamente regolamentato da Apple: la stringa deve contenere da uno a tre numeri separati da punti (ad esempio, 1, 1.2 o 1.2.3). La lunghezza massima è di 18 caratteri. Ogni numero non deve superare 255.

Secondo le Linee guida per la revisione dell'App Store di Apple (2025), App Store Connect non consente il caricamento di un build se Marketing Version differisce dalla versione pubblicata precedente di più di un valore major o minor — questo protegge gli utenti dagli aggiornamenti persi.

Utilizza agvtool per gestire Marketing Version dalla riga di comando — semplifica l'integrazione CI/CD e garantisce la sincronizzazione con Build Number.

Marketing Version su Android

Su Android, Marketing Version viene impostata tramite il parametro versionName nel file build.gradle. A differenza di iOS, Android non impone restrizioni rigide sul formato della stringa di versione.

versionName può contenere qualsiasi carattere: lettere, cifre, trattini e punti. Google Play mostra questa stringa nella scheda dell'app e nell'elenco degli aggiornamenti, ma non la convalida rispetto ad alcun modello.

Tuttavia, Google Play raccomanda di seguire il formato semantico Major.Minor.Patch per uniformità. Ciò facilita la comprensione della versione da parte degli utenti e consente l'analisi automatizzata degli aggiornamenti.

Imposta un versionName che rifletta chiaramente il tipo di versione — major, minor o patch. Questo aiuta gli utenti a valutare rapidamente l'importanza delle modifiche.

Generazione dinamica di versionName

versionName su Android può essere generato dinamicamente in base ai tag Git o alle variabili CI/CD. Ciò semplifica il processo di versionamento ed elimina le discrepanze tra repository e build.

Un approccio tipico consiste nel leggere un tag Git (ad esempio, v2.1.0) e utilizzare il suo valore come versionName. Se il tag è assente, è possibile generare una versione basata sulla data e sul numero di commit.

Questo approccio garantisce che versionName corrisponda sempre allo stato del codice sorgente e non richieda aggiornamenti manuali.

Marketing Version vs Build Number

Marketing Version e Build Number sono due parametri indipendenti che soddisfano scopi diversi. Marketing Version informa l'utente, mentre Build Number identifica tecnicamente il build.

La differenza chiave è l'univocità. Build Number deve essere univoco per ogni build. Marketing Version può ripetersi: più build della stessa versione condividono la stessa Marketing Version ma hanno Build Number diversi.

Secondo la Politica di Google Play (2025), se carichi due APK con la stessa Marketing Version ma Build Number diversi, Google Play accetta entrambi come build diversi della stessa versione. La stessa regola si applica all'App Store.

Ricorda: Build Number è per le macchine, Marketing Version è per le persone. Automatizza il primo e pianifica attentamente la seconda.

Strategie di versionamento

Scegliere una strategia dipende dal tipo di applicazione, dal pubblico e dal processo di rilascio. Tre schemi principali — semantico, calendario e ibrido — coprono la maggior parte degli scenari.

Versionamento Semantico (SemVer) utilizza il formato Major.Minor.Patch e definisce rigorosamente quando incrementare ciascun componente. È ideale per applicazioni con API pubblica e integrazione complessa.

Secondo semver.org (2023), la versione 2.0.0 della specifica SemVer viene utilizzata nell'89% dei progetti mobili open source ed è supportata da tutti i gestori di pacchetti.

Versionamento calendario

Versionamento Calendario (CalVer) utilizza la data di rilascio come versione — ad esempio, 25.06 per giugno 2025. Questo approccio è popolare nelle applicazioni con aggiornamenti frequenti.

CalVer non trasmette informazioni sull'importanza delle modifiche, ma mostra chiaramente la freschezza della versione. Gli utenti capiscono immediatamente che la versione 25.06 è più recente della 25.03.

Scegli il versionamento calendario se la tua app viene aggiornata frequentemente e gli utenti tengono più alla freschezza dei dati che alla portata delle modifiche.

Raccomandazioni di selezione

Per MVP e startup, una versione semantica semplice senza patch (Major.Minor) è adatta. Per prodotti maturi con supporto a lungo termine — SemVer completo. Per app con rilasci continui — CalVer.

Non utilizzare mai la data come Build Number — ciò può causare conflitti con più build al giorno. Build Number deve essere sequenziale o composito, ma sempre monotonamente crescente.

Errori comuni con Marketing Version

Un errore tipico è saltare un componente di versione quando si passa a una nuova linea major. Ad esempio, dopo la versione 1.9.9, la successiva deve essere 2.0.0, non 1.10.0. Questo rompe la semantica e confonde gli utenti.

Un altro problema comune è la discrepanza tra Marketing Version nel codice e nello store di app. Verifica sempre che versionName in build.gradle corrisponda alla versione specificata in Google Play Console o App Store Connect prima di inviare un build per la revisione.

Esempi di configurazione di Marketing Version

Gli esempi di codice mostrano come impostare Marketing Version su entrambe le piattaforme e automatizzarne l'aggiornamento.

Impostare versionName in Android Gradle

Su Android, versionName viene impostato in build.gradle. Il valore può essere statico o letto da una variabile d'ambiente.

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

// Lettura versione da tag Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName viene estratto da un tag Git, garantendo l'allineamento tra la versione del repository e l'applicazione compilata.

Gestire Marketing Version in Xcode

Su iOS, Marketing Version viene impostata tramite Xcode o agvtool. Il comando seguente imposta una nuova versione di marketing.

# Impostare Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# Incremento automatico
xcrun agvtool next-marketing-version

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

Fastlane per entrambe le piattaforme

Fastlane consente di gestire Marketing Version su entrambe le piattaforme da un unico script, semplificando la manutenzione dei progetti multipiattaforma.

# Impostare versione di marketing
increment_version_number(
    version_number: "2.1.0"
)

# Incremento automatico della versione minor
increment_version_number(
    bump_type: "minor"
)

Fastlane funziona su entrambe le piattaforme ed è supportato dalla maggior parte dei servizi CI/CD.