Marketing Version: ce este, diferența de Build Number și setare

Ce este Marketing Version

Marketing Version — este un șir semantic care reprezintă versiunea aplicației pentru utilizatorul final. În iOS este setat prin cheia CFBundleShortVersionString, în Android — prin parametrul versionName.

Termenul „Marketing Version" este folosit oficial în Xcode: în interfața de setări target, câmpul se numește „Marketing Version", iar în Info.plist corespunde cu CFBundleShortVersionString. În Android, echivalentul este versionName, deși termenul este folosit mai rar.

Conform Apple Developer Documentation (2025), Marketing Version trebuie să conțină maximum trei numere separate prin puncte, fără spații și caractere speciale. Fiecare număr nu trebuie să depășească 255.

Alegeți Marketing Version astfel încât să reflecte importanța modificărilor: actualizări majore pentru schimbări radicale, minore pentru funcționalități noi.

Diferența față de Build Number intern

Marketing Version diferă fundamental de Build Number prin scop: primul informează utilizatorul, al doilea — identifică build-ul pentru magazin. Build Number poate crește fără a modifica Marketing Version.

De exemplu, la corectarea unei erori critice într-o versiune lansată, echipa poate recompila aplicația cu aceeași Marketing Version (1.2.0), dar cu Build Number mărit (de la 15 la 16). Utilizatorul va vedea aceeași versiune, dar magazinul va înțelege că build-ul este mai nou.

Această flexibilitate permite dezvoltatorilor să lanseze corecții fără a notifica utilizatorii despre schimbarea versiunii.

Unde se afișează Marketing Version

Marketing Version se afișează în mai multe puncte cheie de interacțiune a utilizatorului cu aplicația. În magazinul de aplicații este vizibilă în cardul aplicației, în descrierea actualizării și în istoricul versiunilor.

Pe dispozitiv, Marketing Version se afișează în setările sistemului (secțiunea „Despre aplicație" sau „Aplicații"), în dialogurile de actualizare prin App Store sau Google Play, precum și în interiorul aplicației pe ecranul „Despre".

O Marketing Version clară ajută utilizatorul să evalueze actualitatea versiunii instalate și să decidă dacă să actualizeze.

Marketing Version pe iOS

Pe iOS, Marketing Version se setează în Xcode prin câmpul „Marketing Version" din fila General a setărilor target. Valoarea se salvează în Info.plist ca CFBundleShortVersionString.

Formatul versiunii este strict reglementat de Apple: șirul trebuie să conțină între una și trei numere separate prin puncte (de exemplu, 1, 1.2 sau 1.2.3). Lungimea maximă — 18 caractere. Fiecare număr nu depășește 255.

Conform Apple App Store Review Guidelines (2025), App Store Connect nu permite încărcarea unui build dacă Marketing Version diferă de versiunea publicată anterior cu mai mult de o valoare majoră sau minoră — acest lucru protejează utilizatorii de actualizări ratate.

Utilizați agvtool pentru gestionarea Marketing Version din linia de comandă — simplifică integrarea cu sistemele CI/CD și garantează sincronizarea cu Build Number.

Marketing Version pe Android

Pe Android, Marketing Version se setează prin parametrul versionName în fișierul build.gradle. Spre deosebire de iOS, Android nu impune restricții stricte asupra formatului șirului versiunii.

versionName poate conține orice caractere: litere, cifre, cratime și puncte. Google Play afișează acest șir în cardul aplicației și în lista actualizărilor, dar nu îl verifică pentru conformitatea cu vreun șablon.

Totuși, Google Play recomandă respectarea formatului semantic Major.Minor.Patch pentru uniformitate. Acest lucru simplifică percepția versiunii de către utilizatori și permite automatizarea analizei actualizărilor.

Specificați un versionName care reflectă clar tipul lansării — actualizare majoră, minoră sau patch. Acest lucru ajută utilizatorii să evalueze rapid importanța modificărilor.

Generarea dinamică a versionName

versionName în Android poate fi generat dinamic pe baza tag-urilor Git sau a variabilelor CI/CD. Acest lucru simplifică procesul de versionare și elimină discrepanțele între depozit și build.

Abordarea tipică — citirea tag-ului Git (de exemplu, v2.1.0) și utilizarea valorii sale ca versionName. Dacă tag-ul lipsește, se poate genera o versiune pe baza datei și numărului commit-ului.

O astfel de abordare garantează că versionName corespunde întotdeauna stării codului sursă și nu necesită actualizare manuală.

Diferența dintre Marketing Version și Build Number

Marketing Version și Build Number — sunt doi parametri independenți care rezolvă sarcini diferite. Marketing Version informează utilizatorul, iar Build Number identifică tehnic build-ul.

Diferența cheie — unicitatea. Build Number trebuie să fie unic pentru fiecare build. Marketing Version se poate repeta: mai multe build-uri ale aceleiași versiuni au aceeași Marketing Version, dar Build Number diferit.

Conform Google Play Policy (2025), dacă se încarcă două APK-uri cu aceeași Marketing Version dar cu Build Number diferit, Google Play le va accepta pe ambele ca build-uri diferite ale aceleiași versiuni. Pentru App Store se aplică o regulă similară.

Amintiți-vă: Build Number — pentru mașini, Marketing Version — pentru oameni. Automatizați primul și planificați cu atenție al doilea.

Strategii de versionare

Alegerea strategiei de versionare depinde de tipul aplicației, de public și de procesul de lansare. Trei scheme principale — semantică, calendaristică și hibridă — acoperă majoritatea scenariilor.

Versiunea semantică (SemVer) utilizează formatul Major.Minor.Patch și stabilește strict când să fie incrementată fiecare componentă. Este ideală pentru aplicațiile cu API public și integrare complexă.

Conform semver.org (2023), versiunea 2.0.0 a specificației SemVer este utilizată în 89% din proiectele mobile open-source și este suportată de toți managerii de pachete.

Versionarea calendaristică

Versionarea calendaristică (CalVer) utilizează data lansării ca versiune — de exemplu, 25.06 pentru iunie 2025. Această abordare este populară în aplicațiile cu actualizări frecvente.

CalVer nu oferă informații despre importanța modificărilor, dar arată excelent prospețimea versiunii. Utilizatorul înțelege imediat că versiunea 25.06 este mai nouă decât 25.03.

Alegeți versionarea calendaristică dacă aplicația dvs. se actualizează frecvent și pentru utilizatori prospețimea datelor este mai importantă decât volumul modificărilor.

Recomandări pentru alegere

Pentru MVP și startup-uri este potrivită o versiune semantică simplă fără patch (Major.Minor). Pentru produse mature cu suport pe termen lung — SemVer complet. Pentru aplicații cu lansări continue — CalVer.

Niciodată nu utilizați data ca Build Number — poate duce la conflicte la mai multe build-uri pe zi. Build Number trebuie să fie secvențial sau compus, dar întotdeauna monoton crescător.

Erori la alegerea Marketing Version

Eroare tipică — omiterea componentei versiunii la tranziția la o nouă linie majoră. De exemplu, după versiunea 1.9.9, următoarea trebuie să fie 2.0.0, nu 1.10.0. Acest lucru încalcă semantica și derutează utilizatorii.

O altă problemă frecventă — neconcordanța Marketing Version în cod și în magazinul de aplicații. Verificați întotdeauna că versionName din build.gradle coincide cu versiunea specificată în Google Play Console sau App Store Connect înainte de a trimite build-ul la revizuire.

Exemple de configurare Marketing Version

Exemplele de cod arată cum să setați Marketing Version pe ambele platforme și să automatizați actualizarea acesteia.

Setarea versionName în Android Gradle

În Android, versionName se setează în build.gradle. Valoarea poate fi statică sau citită dintr-o variabilă de mediu.

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

// Citirea versiunii din tag-ul Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName este extras din tag-ul Git, ceea ce garantează corespondența între versiunea din depozit și cea din aplicația compilată.

Gestionarea Marketing Version în Xcode

În iOS, Marketing Version se setează prin Xcode sau agvtool. Comanda de mai jos setează o nouă versiune de marketing.

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

# Creștere automată
xcrun agvtool next-marketing-version

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

Fastlane pentru ambele platforme

Fastlane permite gestionarea Marketing Version pe ambele platforme dintr-un singur script, simplificând suportul proiectelor cross-platform.

# Setarea versiunii de marketing
increment_version_number(
    version_number: "2.1.0"
)

# Creștere automată a versiunii minore
increment_version_number(
    bump_type: "minor"
)

Fastlane funcționează pe ambele platforme și este suportat de majoritatea serviciilor CI/CD.