Version Name: esența parametrului și setarea

Ce este Version Name

Version Name — este un șir semantic care identifică lansarea aplicației pentru utilizator. Spre deosebire de identificatorii tehnici de construire, acest parametru poartă încărcătură semantică: pe baza lui, utilizatorul evaluează cât de mult diferă noua actualizare de cea anterioară.

Version Name se afișează în cardul aplicației în Google Play și App Store, în secțiunea „Despre aplicație” pe dispozitiv, precum și în dialogurile de sistem de actualizare. Dezvoltatorii îl specifică în fișierele de configurare ale proiectului înainte de construirea versiunii de lansare.

Conform Semantic Versioning 2.0 (2023), formatul Major.Minor.Patch este utilizat în 78% din aplicațiile mobile. Versiunea majoră se modifică la schimbări incompatibile ale API, minoră — la adăugarea de funcționalități, patch — la corectarea erorilor.

Utilizați Version Name pentru comunicarea cu utilizatorul: acesta trebuie să înțeleagă imediat cât de mare este actualizarea oferită — majoră, minoră sau corectivă.

Structura versiunii semantice

Versiunea semantică constă din trei numere separate prin puncte: Major.Minor.Patch. Fiecare dintre aceste componente corespunde unui anumit nivel de modificări în aplicație.

Versiunea majoră (Major) crește la introducerea de schimbări radicale care rup compatibilitatea inversă. Versiunea minoră (Minor) adaugă funcționalități noi fără a le afecta pe cele existente. Patch conține doar corecturi de erori.

De exemplu, versiunea 3.2.1 înseamnă: a treia versiune majoră, a doua actualizare minoră, primul patch. Acest sistem este înțeles atât de dezvoltatori, cât și de utilizatori.

Unde se afișează Version Name

Version Name este vizibil utilizatorului în câteva locuri cheie. În magazinul de aplicații se afișează în antetul cardului aplicației și în lista de actualizări. Pe dispozitiv — în setările de sistem în secțiunea „Despre aplicație”.

În Google Play, Version Name se afișează sub numele aplicației și influențează decizia utilizatorului de actualizare. În App Store, șirul versiunii se afișează în același loc la vizualizarea paginii aplicației.

Conform cercetării Apptentive (2024), 67% dintre utilizatori verifică versiunea aplicației înainte de actualizare, iar o semantică inteligibilă crește conversia la instalare cu 23%.

Version Name pe Android

Pe Android, Version Name se setează cu parametrul versionName în fișierul build.gradle (la nivel de modul). Acest parametru este un șir și poate conține orice caractere, inclusiv puncte, cratime și litere.

Parametrul se declară în interiorul blocului android.defaultConfig împreună cu parametrul obligatoriu versionCode. Android nu impune restricții asupra formatului șirului, dar Google Play recomandă utilizarea formatului semantic.

Conform Android Developers (2025), Google Play folosește versionName pentru afișarea în interfața magazinului, dar nu analizează conținutul acestuia programatic — doar versionCode influențează logica de actualizare.

Indicați Version Name în formatul Major.Minor.Patch și sincronizați-l cu tag-ul din sistemul de control al versiunilor pentru identificarea exactă a lansării.

Particularitățile versionName în Gradle

Gradle permite setarea versionName static în build.gradle sau dinamic prin scripturi de construire. Generarea dinamică este utilă pentru construirile automate de noapte și pipeline-urile CI/CD.

În build.gradle puteți utiliza variabile de mediu, parametri de linie de comandă sau apeluri de scripturi shell pentru a forma versionName. Abordarea tipică este citirea versiunii din fișierul version.properties.

Această flexibilitate permite echipelor să automatizeze procesul de versionare și să elimine factorul uman la pregătirea lansării.

Version Name pe iOS

Pe iOS, Version Name se setează cu cheia CFBundleShortVersionString în fișierul Info.plist. Acesta este un parametru obligatoriu pentru publicarea aplicației în App Store și este strict tipizat ca șir.

Spre deosebire de Android, App Store Connect verifică formatul Version Name și cere conformitatea cu șablonul de numere separate prin puncte. Lungimea maximă a șirului este de 18 caractere, iar fiecare componentă a versiunii nu poate depăși 255.

Conform Apple Developer Documentation (2025), CFBundleShortVersionString este utilizat de App Store pentru afișarea versiunii în interfața magazinului și în dialogurile de sistem de pe dispozitivul utilizatorului.

La încărcarea construirii în App Store Connect, asigurați-vă că Version Name corespunde versiunii indicate în materialele de marketing — aceasta simplifică comunicarea cu utilizatorii.

Integrarea cu Xcode

Xcode oferă o interfață grafică pentru modificarea Version Name în setările target-ului. Câmpul „Marketing Version” se află pe fila General în secțiunea Identity. Modificările se salvează automat în Info.plist.

Pentru automatizare, puteți utiliza scripturi de construire în Xcode Build Phases sau utilitarul agvtool (Apple Generic Version Tool). agvtool permite gestionarea versiunilor din linia de comandă și se integrează cu CI/CD.

O astfel de abordare este deosebit de convenabilă la utilizarea fastlane sau Jenkins pentru construirea și livrarea automată a aplicațiilor.

Diferențele dintre Version Name și Build Number

Version Name și Build Number îndeplinesc sarcini diferite în procesul de dezvoltare. Version Name este un șir utilizator, iar Build Number este un identificator numeric intern care identifică unic fiecare construire.

Build Number (versionCode în Android, CFBundleVersion în iOS) trebuie să crească cu fiecare construire nouă și este utilizat de magazinele de aplicații pentru a determina care versiune este mai nouă. Version Name poate rămâne neschimbat pentru mai multe construirii ale aceleiași versiuni.

Conform Google Play Policy (2025), două aplicații cu același versionCode sunt considerate aceeași versiune — versionCode trebuie să fie unic pentru fiecare APK. Version Name nu participă la această verificare.

Creșteți întotdeauna Build Number la fiecare construire și modificați Version Name doar la schimbarea funcționalității — aceasta previne conflictele la publicare.

Cum să alegem Version Name

Alegerea Version Name depinde de strategia de versionare a echipei. Cea mai răspândită abordare este versionarea semantică (SemVer), dar există și scheme alternative, precum versionarea calendaristică sau versionarea după data lansării.

Semantic Versioning 2.0 recomandă formatul Major.Minor.Patch cu sufixe opționale pre-release. Pentru aplicațiile mobile, este populară și schema Major.Minor, unde patch-ul este omis pentru simplificarea percepției.

Versionarea calendaristică (CalVer) utilizează data lansării ca număr de versiune — de exemplu, 25.06 (an și lună). Această abordare este convenabilă pentru aplicațiile cu lansări frecvente, unde semantica nu are importanță.

Recomandări pentru alegerea schemei

Versionarea semantică este potrivită pentru aplicațiile cu API public, unde compatibilitatea inversă este importantă. Utilizatorii și integratorii înțeleg ce modificări să aștepte la actualizare.

Versionarea calendaristică se alege pentru aplicațiile unde pentru utilizator este importantă prospetimea lansării, nu amploarea modificărilor. De exemplu, agregatoarele de știri sau aplicațiile meteo.

Schema hibridă combină ambele abordări: Major.Minor.RC, unde RC este numărul construirii pentru un anumit candidat de lansare. O astfel de schemă este convenabilă în testarea beta activă.

Exemple de configurare Version Name

Exemplele de cod de mai jos arată cum să setați Version Name pe Android și iOS. Pentru Android se utilizează Gradle, pentru iOS — Xcode Build Settings cu agvtool.

Configurarea versionName în Android

În Android, versiunea se setează în fișierul app/build.gradle în interiorul blocului defaultConfig. Parametrul versionName acceptă o valoare de șir.

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

versionName poate fi, de asemenea, citit dintr-un fișier extern sau generat dinamic cu ajutorul Gradle Script.

Generarea dinamică a versionName

Versiunea dinamică este formată din variabilele de mediu ale sistemului CI/CD. Aceasta garantează că fiecare construire primește numărul corect de versiune.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

O astfel de abordare automatizează versionarea și elimină riscul de neconcordanță între construire și tag-ul din depozit.

Configurarea CFBundleShortVersionString în iOS

În iOS, versiunea poate fi setată prin Xcode sau prin linia de comandă cu agvtool.

# Setarea versiunii de marketing
xcrun agvtool new-marketing-version 2.1.0

# Citirea versiunii curente
xcrun agvtool what-marketing-version

agvtool actualizează automat Info.plist și sincronizează versiunea între toate target-urile din proiectul Xcode.