Build Number — ce este, semnificația parametrului și incrementare

Ce este Build Number

Build Number — este un identificator numeric întreg unic care se atribuie fiecărei compilări a aplicației mobile. Magazinele de aplicații îl folosesc pentru a determina noutatea versiunii — cu cât numărul este mai mare, cu atât compilarea este mai nouă.

În Android acest parametru se numește versionCode, în iOS — CFBundleVersion. Ambii parametri sunt obligatorii pentru publicare și trebuie să crească monoton cu fiecare compilare nouă.

Conform datelor Google Play Console Help (2025), versionCode este verificat la fiecare încărcare APK: dacă compilarea încărcată are versionCode mai mic sau egal cu cea deja publicată, Google Play respinge fișierul cu eroare.

Folosiți Build Number pentru urmărirea internă a compilărilor — asociați numărul cu commit hash-ul din sistemul de control al versiunilor pentru a identifica rapid o versiune problemă.

De ce este necesar Build Number

Build Number rezolvă problema identificării unice a fiecărei versiuni compilate a aplicației. Fără el, este imposibil de determinat care compilare este mai nouă dacă Version Name nu s-a schimbat.

Magazinele de aplicații, precum Google Play și App Store, folosesc Build Number pentru a rezolva conflictele la actualizare. Dacă utilizatorul instalează o versiune nouă peste una veche, sistemul compară Build Number și oferă actualizarea doar la o valoare mai mare.

Această mecanică este critică pentru livrarea corectă a actualizărilor: fără un Build Number care crește monoton, utilizatorii pot rămâne pe o versiune veche a aplicației.

Formatele Build Number

Build Number poate fi un număr secvențial simplu (1, 2, 3...) sau compus, care codifică informații suplimentare. Numerele compuse includ adesea data compilării sau numărul compilării sistemului CI/CD.

Pentru Android versionCode este un număr întreg de tip int, valoarea maximă — 2100000000. Pentru iOS CFBundleVersion este un șir de trei numere separate prin puncte, fiecare nu mai mare de 255.

Conform datelor Apple Developer (2025), CFBundleVersion suportă până la 3 componente, dar App Store le folosește ca un singur număr de ordine pentru compararea versiunilor.

Build Number pe Android

Pe Android Build Number se setează cu parametrul versionCode în fișierul build.gradle. Este un număr întreg care trebuie să fie unic pentru fiecare versiune a aplicației publicată în Google Play.

Parametrul se declară în blocul android.defaultConfig și trebuie să crească cu fiecare lansare nouă. Google Play nu permite încărcarea unui APK cu un versionCode care a fost deja folosit pentru o altă versiune a aceleiași aplicații.

Conform datelor Google Play Developer API (2025), valoarea maximă a versionCode este 2100000000. Se recomandă să începeți de la 1 și să creșteți cu 1 pentru fiecare compilare nouă pentru a evita epuizarea limitei.

Folosiți un versionCode compus care codifică numărul versiunii: Major * 1000000 + Minor * 1000 + Patch — aceasta simplifică maparea la versiunea semantică.

Limitări ale versionCode în Android

versionCode are limitări stricte: este un număr întreg de 32 de biți cu semn, deci valoarea maximă este 2100000000. La epuizarea limitei, aplicația nu va putea fi actualizată în Google Play.

Pentru Android App Bundle, versionCode este specificat și în modulul base, iar fiecare modul feature poate avea propriul versionCode. Google Play le combină într-un singur sistem de verificare.

Această limitare trebuie luată în considerare la alegerea strategiei de versionare — o creștere prea rapidă a numărului poate duce la probleme pe termen lung.

Build Number pe iOS

Pe iOS Build Number se setează cu cheia CFBundleVersion în fișierul Info.plist. Spre deosebire de Android, acest parametru este un șir de caractere, dar trebuie de asemenea să crească cu fiecare compilare nouă.

Formatul CFBundleVersion — de la unu la trei numere separate prin puncte. Fiecare număr nu poate depăși 255. App Store interpretează șirul ca o secvență de numere pentru comparare: 1.0.1 este considerat mai nou decât 1.0.0.

Conform datelor Apple Developer Documentation (2025), App Store Connect necesită unicitatea CFBundleVersion pentru fiecare compilare încărcată. Dacă încărcați o compilare cu un număr deja folosit, sistemul o va respinge.

Gestionați CFBundleVersion prin agvtool sau scripturi de compilare Xcode pentru a garanta creșterea monotonă a numărului la fiecare compilare.

Integrare cu setările de compilare Xcode

Xcode permite gestionarea CFBundleVersion prin setările Build Settings. Câmpul „Current Project Version“ setează valoarea de bază, iar scripturile Build Phase o pot crește automat.

Pentru CI/CD folosiți pluginul fastlane increment_build_number, care citește versiunea curentă din Info.plist și o crește cu o valoare dată. Aceasta garantează unicitatea fiecărei compilări.

Această abordare automatizează complet gestionarea Build Number și elimină erorile umane la pregătirea lansării.

Incrementarea automată a Build Number

Incrementarea automată a Build Number este o practică standard în pipeline-urile moderne CI/CD. Creșterea manuală a numărului de compilare duce la erori și conflicte la publicare.

GitHub Actions, GitLab CI și Jenkins oferă variabile încorporate cu numărul compilării. Aceste variabile sunt folosite în scripturile Gradle sau Xcode pentru substituirea automată a Build Number.

Conform datelor GitLab CI Documentation (2025), variabila CI_PIPELINE_IID garantează un număr unic pentru fiecare pipeline, ceea ce este ideal pentru utilizarea ca Build Number.

Configurați incrementarea automată la nivelul CI/CD — aceasta va elimina necesitatea modificării manuale a Build Number la fiecare commit în ramura de lansare.

Instrumente populare de automatizare

GitHub Actions suportă variabila încorporată run_number, care crește automat pentru fiecare execuție a pipeline-ului. Valoarea poate fi transmisă către Gradle prin versionCode.

Jenkins folosește variabila BUILD_NUMBER, disponibilă în toate etapele compilării. Pentru proiectele Xcode, Jenkins execută agvtool cu acest număr.

Alegeți instrumentul care este integrat în stiva dvs. tehnologică pentru a minimiza configurarea suplimentară.

Build Number și Version Name

Build Number și Version Name funcționează ca o pereche: primul — pentru mașini, al doilea — pentru oameni. Build Number asigură unicitatea tehnică, Version Name — semantica ușor de înțeles de utilizator.

În Android aceste două componente sunt independente: versionCode poate crește fără modificarea versionName (de exemplu, pentru corectarea unei erori de compilare). În iOS, CFBundleVersion nu este legat de CFBundleShortVersionString.

Conform datelor Stack Overflow Developer Survey (2024), 82% dintre echipe folosesc incrementarea automată a Build Number, dar doar 45% automatizează actualizarea Version Name — aceasta este una dintre cauzele frecvente ale erorilor la lansare.

Creșteți întotdeauna Build Number la fiecare compilare, chiar dacă Version Name nu se schimbă — aceasta garantează funcționarea corectă a mecanismului de actualizare în magazinele de aplicații.

Cele mai bune practici pentru Build Number

Începeți versionCode de la 1 și creșteți cu 1 pentru fiecare compilare. Pentru iOS folosiți o abordare analogă cu CFBundleVersion. Evitați numerele compuse dacă nu este strict necesar — un număr secvențial simplu este mai ușor de urmărit.

Asociați Build Number cu numărul compilării sistemului CI/CD — aceasta simplifică trasabilitatea de la eroare la commit-ul specific. Git tag cu numărul compilării și versiunea este cea mai bună practică pentru controlul lansărilor.

Exemple de configurare Build Number

Exemplele de cod arată cum să configurați incrementarea automată a Build Number pe ambele platforme.

versionCode în Gradle cu variabila CI

În Android versionCode poate fi setat printr-o variabilă de mediu CI/CD. Dacă variabila nu este setată, se folosește valoarea implicită.

android {
    defaultConfig {
        versionCode System.getenv("CI_PIPELINE_ID")?.toInteger() ?: 1
        versionName "1.2.0"
    }
}

versionCode primește valoarea din variabila CI/CD, ceea ce garantează unicitatea numărului pentru fiecare compilare în pipeline.

Incrementarea CFBundleVersion prin agvtool

În iOS pentru creșterea automată a Build Number se folosește agvtool, care este încorporat în Xcode Command Line Tools.

# Creșterea numărului de build cu 1
xcrun agvtool next-version -all

# Setarea unui număr de build specific
xcrun agvtool new-version -all "3.0.1"

Indicatorul -all actualizează versiunea în toate target-urile proiectului, ceea ce garantează sincronizarea valorilor între aplicația principală și extensii.

Fastlane pentru automatizare

Fastlane — instrument popular pentru automatizarea compilării aplicațiilor mobile. Pluginul increment_build_number crește automat Build Number.

increment_build_number(
    build_number: ENV["BUILD_NUMBER"] ||
                 latest_testflight_build_number + 1
)

Fastlane se integrează cu orice sistem CI/CD și suportă atât proiecte Android, cât și iOS.