Version Code: ce este, identificatorul numeric și actualizări

Ce este Version Code în Android

Version Code — este un număr întreg de tip Integer care este atribuit fiecărei compilări a aplicației Android. Spre deosebire de Version Name, Version Code nu este afișat utilizatorului și este utilizat exclusiv de sistemul de operare și Google Play pentru compararea versiunilor la instalarea actualizărilor.

Formatul Version Code

Version Code trebuie să fie un număr întreg pozitiv în intervalul de la 1 la 2100000000. Fiecare compilare ulterioară trebuie să aibă un Version Code strict mai mare decât precedenta. Dacă dezvoltatorul a lansat o compilare cu Version Code 5, următoarea publicație poate utiliza 6, 7 sau orice număr mai mare de 5, dar nu 4 și nici 5 din nou.

Istoricul apariției

Google a introdus împărțirea în Version Code și Version Name odată cu lansarea Android SDK în 2007. Version Code a fost conceput ca un identificator mașină pentru compararea automată a versiunilor, în timp ce Version Name — ca o etichetă lizibilă pentru om. Această separare permite dezvoltatorului să denumească versiunea după cum dorește, păstrând în același timp o ordine strictă a actualizărilor prin codul numeric.

Cum funcționează versionarea prin Version Code

Mecanismul de comparare Version Code este încorporat în sistemul de operare Android și în magazinul Google Play. La fiecare publicare, Google Play verifică dacă Version Code al noii compilări este mai mare decât codul versiunii instalate. Dacă condiția nu este îndeplinită, publicarea este respinsă cu o eroare.

Procesul de verificare a actualizării

Când dispozitivul contactează Google Play pentru a verifica actualizări, serverul compară Version Code al aplicației instalate cu cel maxim disponibil în magazin. Dacă codul de pe server este mai mare — se pornește descărcarea și instalarea actualizării. Utilizatorul vede Version Name specificat de dezvoltator, dar decizia privind actualizarea se ia pe baza Version Code.

Incrementarea Version Code

Dezvoltatorii aplică diferite strategii de incrementare a Version Code. Cea mai simplă este creșterea cu 1 la fiecare compilare. Pentru conductele CI/CD se utilizează adesea timestamp sau numărul de compilare: 2026070301 (an-lună-zi-număr). Este important ca codul să crească monoton și să nu se repete între diferite compilări și track-uri Google Play.

• Increment monoton — creșterea cu 1 la fiecare commit în ramura release
• Format timestamp — 20260703 pentru compilări zilnice, 2026070301 pentru mai multe într-o zi
• SemVer în numere — 100010000 pentru versiunea 1.1.0 (major 1, minor 1, patch 0)
• Numărul de build — utilizarea BUILD_NUMBER din sistemul CI (Jenkins, GitHub Actions)

Diferențele dintre Version Code și Version Name

Version Code și Version Name — două câmpuri independente în build.gradle care îndeplinesc funcții diferite. Version Code este un identificator intern pentru sistem, Version Name este o etichetă de marketing pentru utilizator. Ele se pot modifica independent unul de celălalt.

Version Name pentru utilizator

Version Name — este un șir care este afișat în setările aplicației, în Google Play și în dialogurile de actualizare. Dezvoltatorul poate specifica orice format: 1.0.0, 2.3.1-beta, 3.0-rc1. Pentru compararea versiunilor text, Version Name nu este utilizat — Google Play se bazează întotdeauna pe Version Code.

Scenarii de divergență

Este posibilă situația când Version Code crește, iar Version Name rămâne neschimbat. De exemplu, dacă dezvoltatorul repară o eroare critică într-o compilare hotfix fără a modifica funcționalitatea. Version Name rămâne 2.0.0, iar Version Code se schimbă de la 5 la 6. Google Play va gestiona corect o astfel de actualizare.

// Exemplu: version name nu se schimbă, code crește
android {
    defaultConfig {
        versionCode 6  // A fost 5 — hotfix fără funcții noi
        versionName "2.0.0"  // Nu s-a schimbat
    }
}

// Verificarea versiunilor în runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Cod: $code, Nume: $name")

Configurarea Version Code în build.gradle

Configurarea Version Code se realizează în fișierul build.gradle al modulului aplicației. Câmpul versionCode primește un număr întreg și se află în blocul defaultConfig. Pentru diferite compilări flavour se pot stabili valori proprii prin câmpul versionCode în configurarea produsului.

Configurarea de bază

// 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
        }
    }
}

Product flavors permit utilizarea diferitelor Version Code pentru configurații diferite: versiunea demo, versiune separată pentru tablete. Dacă în proiect se utilizează flavors, Version Code final se compune din numărul de bază și incrementul specific flavour-ului. Google Play urmărește fiecare combinație în mod independent.

Automatizarea incrementării prin CI

În conductele CI/CD (GitHub Actions, GitLab CI, Jenkins) Version Code este adesea generat automat pe baza numărului de compilare sau a datei. Aceasta elimină erorile umane la actualizarea manuală. Scriptul citește Version Code curent din build.gradle, îl incrementează și îl scrie înapoi înainte de începerea compilării.

// Incrementarea automată a 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
    }
}

Regulile Version Code pentru publicarea în Google Play

Google Play are reguli stricte pentru Version Code la publicarea și actualizarea aplicațiilor. Încălcarea acestor reguli duce la respingerea compilării sau imposibilitatea de a lansa o actualizare. Dezvoltatorul trebuie să înțeleagă limitările și strategiile de gestionare a codului în toate etapele ciclului de viață.

Regula creșterii monotone

Google Play nu permite încărcarea unui APK sau AAB al cărui Version Code este mai mic sau egal cu cel publicat curent. Această regulă funcționează pentru fiecare track (production, beta, alpha) în mod independent. Dacă în production a fost încărcată o compilare cu Version Code 10, iar în alpha — cu codul 5, track-ul alpha poate fi actualizat la 6, 7, 8 sau 9, dar production rămâne la 10.

Migrarea între track-uri

La promovarea compilării din alpha în beta, apoi în production, Version Code trebuie să crească la fiecare etapă. Dacă versiunea alpha are codul 10, beta poate utiliza 11, iar production — 12. Nu se poate lansa în production o compilare cu codul 10 dacă alpha utilizează deja 10, chiar dacă production nu l-a văzut încă.

• Monotonous increment — fiecare compilare într-un track are Version Code mai mare decât precedenta din același track
• Cross-track awareness — la promovarea între track-uri, Version Code crește secvențial
• Internal testing — track-ul pentru testare internă utilizează aceleași reguli de monotonie
• Multiple APKs — vechiul format de publicare necesita un Version Code unic pentru fiecare APK

Erori la specificarea Version Code

Cea mai frecventă eroare — coincidența Version Code în diferite compilări încărcate într-un singur track. Google Play returnează eroarea APK_VERSION_CODE_ALREADY_EXISTS. O altă eroare — depășirea valorii maxime 2100000000, ceea ce duce la o eroare de compilare. Pentru a evita conflictele, utilizați generarea automată a codului în sistemul CI cu legătură la numărul de compilare sau data compilării.

Dezvoltatorii fac adesea și eroarea de a nu crește Version Code la compilarea hotfix pentru un track alternativ. Dacă production are codul 15, iar track-ul alpha a rămas la 14, la promovarea alpha în production Google Play va respinge compilarea deoarece codul său este mai mic decât production curent. Urmăriți monotonitatea codului în toate track-urile simultan — pentru aceasta este convenabil să utilizați un singur fișier version.properties din care toate track-urile citesc valoarea curentă.