Version Code: cos'è, identificatore numerico e aggiornamenti

Cos'è il Version Code in Android

Version Code è un numero intero di tipo Integer assegnato a ogni compilazione di un'applicazione Android. A differenza del Version Name, il Version Code non viene mostrato all'utente e viene utilizzato esclusivamente dal sistema operativo e da Google Play per confrontare le versioni durante l'installazione degli aggiornamenti.

Formato del Version Code

Version Code deve essere un numero intero positivo compreso tra 1 e 2100000000. Ogni compilazione successiva deve avere un Version Code strettamente maggiore della precedente. Se uno sviluppatore ha pubblicato una compilazione con Version Code 5, la pubblicazione successiva può utilizzare 6, 7 o qualsiasi numero maggiore di 5, ma non 4 e non di nuovo 5.

Storia dell'origine

Google ha introdotto la separazione tra Version Code e Version Name con il rilascio dell'Android SDK nel 2007. Il Version Code è stato concepito come un identificatore macchina per il confronto automatico delle versioni, mentre il Version Name è stato creato come un'etichetta leggibile dall'uomo. Questa separazione consente allo sviluppatore di nominare la versione come desidera, mantenendo un ordine rigoroso degli aggiornamenti tramite il codice numerico.

Come funziona il versionamento tramite Version Code

Il meccanismo di confronto del Version Code è integrato nel sistema operativo Android e nel Google Play Store. A ogni pubblicazione, Google Play verifica che il Version Code della nuova compilazione sia maggiore del codice della versione installata. Se la condizione non viene soddisfatta, la pubblicazione viene rifiutata con un errore.

Processo di verifica degli aggiornamenti

Quando un dispositivo contatta Google Play per verificare la presenza di aggiornamenti, il server confronta il Version Code dell'applicazione installata con il massimo disponibile nel negozio. Se il codice sul server è maggiore, vengono avviati il download e l'installazione dell'aggiornamento. L'utente vede il Version Name specificato dallo sviluppatore, ma la decisione sull'aggiornamento viene presa in base al Version Code.

Incremento del Version Code

Gli sviluppatori applicano diverse strategie per incrementare il Version Code. La più semplice è l'aumento di 1 a ogni compilazione. Per le pipeline CI/CD, viene spesso utilizzato un timestamp o il numero di compilazione: 2026070301 (anno-mese-giorno-numero). È importante che il codice aumenti monotonamente e non si ripeta tra diverse compilazioni e tracce di Google Play.

• Incremento monotono — aumento di 1 a ogni commit nel ramo di rilascio
• Formato timestamp — 20260703 per compilazioni giornaliere, 2026070301 per più compilazioni al giorno
• SemVer in numeri — 100010000 per la versione 1.1.0 (major 1, minor 1, patch 0)
• Numero di compilazione — utilizzo di BUILD_NUMBER dal sistema CI (Jenkins, GitHub Actions)

Differenze tra Version Code e Version Name

Version Code e Version Name sono due campi indipendenti in build.gradle che svolgono funzioni diverse. Il Version Code è un identificatore interno per il sistema, il Version Name è un'etichetta di marketing per l'utente. Possono cambiare indipendentemente l'uno dall'altro.

Version Name per l'utente

Version Name è una stringa che viene visualizzata nelle impostazioni dell'applicazione, in Google Play e nei dialoghi di aggiornamento. Lo sviluppatore può specificare qualsiasi formato: 1.0.0, 2.3.1-beta, 3.0-rc1. Il Version Name non viene utilizzato per confrontare le versioni testuali — Google Play si basa sempre sul Version Code.

Scenari di divergenza

È possibile una situazione in cui il Version Code aumenta mentre il Version Name rimane lo stesso. Ad esempio, se uno sviluppatore corregge un bug critico in una compilazione hotfix senza modificare la funzionalità. Il Version Name rimane 2.0.0, mentre il Version Code passa da 5 a 6. Google Play gestirà correttamente questo aggiornamento.

// Esempio: il version name non cambia, il codice aumenta
android {
    defaultConfig {
        versionCode 6  // Era 5 — hotfix senza nuove funzionalità
        versionName "2.0.0"  // Non cambiato
    }
}

// Controllo delle versioni in runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Configurazione del Version Code in build.gradle

La configurazione del Version Code viene eseguita nel file build.gradle del modulo dell'applicazione. Il campo versionCode accetta un numero intero e fa parte del blocco defaultConfig. Per diverse compilazioni di flavor, è possibile impostare valori personalizzati tramite il campo versionCode nella configurazione del prodotto.

Configurazione di base

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

I Product flavors consentono di utilizzare diversi Version Code per configurazioni differenti: versione demo, versione separata per tablet. Se nel progetto vengono utilizzati flavor, il Version Code finale è composto dal numero base e dall'incremento specifico del flavor. Google Play tiene traccia di ogni combinazione in modo indipendente.

Automazione dell'incremento tramite CI

Nelle pipeline CI/CD (GitHub Actions, GitLab CI, Jenkins), il Version Code viene spesso generato automaticamente in base al numero di compilazione o alla data. Ciò elimina l'errore umano durante gli aggiornamenti manuali. Lo script legge il Version Code corrente da build.gradle, lo incrementa e lo riscrive prima di avviare la compilazione.

// Incremento automatico del Version Code
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Particolarità del Version Code per la pubblicazione su Google Play

Google Play ha regole rigide per il Version Code durante la pubblicazione e l'aggiornamento delle applicazioni. La violazione di queste regole comporta il rifiuto della compilazione o l'impossibilità di pubblicare un aggiornamento. Lo sviluppatore deve comprendere i limiti e le strategie di gestione del codice in tutte le fasi del ciclo di vita.

Regola dell'incremento monotono

Google Play non consente il caricamento di un APK o AAB il cui Version Code sia inferiore o uguale a quello attualmente pubblicato. Questa regola si applica a ciascun canale (production, beta, alpha) in modo indipendente. Se una compilazione con Version Code 10 è stata caricata in production e una con codice 5 è in alpha, il canale alpha può essere aggiornato a 6, 7, 8 o 9, ma production rimane a 10.

Migrazione tra canali

Durante la promozione di una compilazione da alpha a beta e poi a production, il Version Code deve aumentare in ogni fase. Se la versione alpha ha codice 10, beta può utilizzare 11 e production 12. Non è possibile distribuire in production una compilazione con codice 10 se alpha sta già utilizzando 10, anche se production non lo ha ancora visto.

• Incremento monotono — ogni compilazione in un canale ha un Version Code maggiore della precedente nello stesso canale
• Consapevolezza tra canali — durante la promozione tra canali, il Version Code aumenta sequenzialmente
• Test interni — il canale di test interno utilizza le stesse regole di monotonicità
• APK multipli — il vecchio formato di pubblicazione richiedeva un Version Code univoco per ogni APK

Errori nella specifica del Version Code

L'errore più comune è la corrispondenza del Version Code in diverse compilazioni caricate nello stesso canale. Google Play restituisce l'errore APK_VERSION_CODE_ALREADY_EXISTS. Un altro errore è il superamento del valore massimo di 2100000000, che causa un errore di compilazione. Per evitare conflitti, utilizzare la generazione automatica del codice nel sistema CI legata al numero di compilazione o alla data di compilazione.

Gli sviluppatori commettono spesso anche l'errore di non incrementare il Version Code durante la creazione di una hotfix per un canale alternativo. Se production ha codice 15 e il canale alpha è rimasto a 14, durante la promozione di alpha a production, Google Play rifiuterà la compilazione perché il suo codice è inferiore al codice corrente di production. Monitorare la monotonicità del codice in tutti i canali simultaneamente — per questo è conveniente utilizzare un singolo file version.properties da cui tutti i canali leggono il valore corrente.