Build Number — wat is het, betekenis van de parameter en increment

Wat is Build Number

Build Number — is een unieke numerieke identificatie die aan elke build van een mobiele app wordt toegewezen. App-winkels gebruiken het om de nieuwheid van een versie te bepalen — hoe hoger het nummer, hoe nieuwer de build.

In Android heet deze parameter versionCode, in iOS — CFBundleVersion. Beide parameters zijn verplicht voor publicatie en moeten monotoon stijgen met elke nieuwe build.

Volgens Google Play Console Help (2025) wordt versionCode gecontroleerd bij elke APK-upload: als de geüploade build een versionCode heeft die kleiner is dan of gelijk aan de reeds gepubliceerde, wijst Google Play het bestand af met een fout.

Gebruik Build Number voor interne tracking van builds — koppel het nummer aan een commit hash in het versiebeheersysteem om een problematische release snel te identificeren.

Waarom is Build Number nodig

Build Number lost het probleem op van unieke identificatie van elke gebouwde versie van de app. Zonder dit is het onmogelijk te bepalen welke build nieuwer is als Version Name niet is veranderd.

App-winkels zoals Google Play en App Store gebruiken Build Number om conflicten bij updates op te lossen. Als een gebruiker een nieuwe versie over een oude installeert, vergelijkt het systeem Build Number en biedt het alleen een update aan bij een hogere waarde.

Deze mechaniek is cruciaal voor correcte levering van updates: zonder een monotoon stijgend Build Number kunnen gebruikers vast komen te zitten op een oude versie van de app.

Formaten van Build Number

Build Number kan een eenvoudig opeenvolgend nummer zijn (1, 2, 3...) of samengesteld, met extra informatie gecodeerd. Samengestelde nummers bevatten vaak de builddatum of het buildnummer van het CI/CD-systeem.

Voor Android is versionCode een geheel getal van het type int, maximale waarde — 2100000000. Voor iOS is CFBundleVersion een string van drie door punten gescheiden getallen, elk niet groter dan 255.

Volgens Apple Developer (2025) ondersteunt CFBundleVersion tot 3 componenten, maar App Store gebruikt ze als één enkel volgnummer voor het vergelijken van versies.

Build Number op Android

Op Android wordt Build Number ingesteld met de parameter versionCode in het bestand build.gradle. Het is een geheel getal dat uniek moet zijn voor elke versie van de app die in Google Play wordt gepubliceerd.

De parameter wordt gedeclareerd in het blok android.defaultConfig en moet stijgen met elke nieuwe release. Google Play staat niet toe dat een APK wordt geüpload met een versionCode die al is gebruikt voor een andere versie van dezelfde app.

Volgens Google Play Developer API (2025) is de maximale waarde van versionCode 2100000000. Het wordt aanbevolen om te beginnen bij 1 en met 1 te verhogen voor elke nieuwe build om uitputting van de limiet te voorkomen.

Gebruik een samengestelde versionCode die het versienummer codeert: Major * 1000000 + Minor * 1000 + Patch — dit vereenvoudigt de koppeling aan de semantische versie.

Beperkingen van versionCode in Android

versionCode heeft strikte beperkingen: het is een 32-bits geheel getal met teken, dus de maximale waarde is 2100000000. Bij uitputting van de limiet kan de app niet worden bijgewerkt in Google Play.

Voor Android App Bundle wordt versionCode ook opgegeven in de basismodule en elke feature-module kan zijn eigen versionCode hebben. Google Play combineert ze in één verificatiesysteem.

Deze beperking moet in overweging worden genomen bij het kiezen van een versiestrategie — te snelle groei van het nummer kan op lange termijn tot problemen leiden.

Build Number op iOS

Op iOS wordt Build Number ingesteld met de sleutel CFBundleVersion in het bestand Info.plist. In tegenstelling tot Android is deze parameter een string, maar moet ook stijgen met elke nieuwe build.

Het formaat van CFBundleVersion — één tot drie door punten gescheiden getallen. Elk getal mag niet groter zijn dan 255. App Store interpreteert de string als een reeks getallen voor vergelijking: 1.0.1 wordt als nieuwer beschouwd dan 1.0.0.

Volgens Apple Developer Documentation (2025) vereist App Store Connect uniciteit van CFBundleVersion voor elke geüploade build. Als een build met een reeds gebruikt nummer wordt geüpload, wijst het systeem deze af.

Beheer CFBundleVersion via agvtool of Xcode-buildscripts om monotone stijging van het nummer bij elke build te garanderen.

Integratie met Xcode Build Settings

Xcode maakt het mogelijk CFBundleVersion te beheren via Build Settings. Het veld „Current Project Version“ stelt de basiswaarde in en Build Phase-scripts kunnen deze automatisch verhogen.

Voor CI/CD gebruikt u de fastlane-plugin increment_build_number, die de huidige versie uit Info.plist leest en met een bepaalde waarde verhoogt. Dit garandeert de uniciteit van elke build.

Deze aanpak automatiseert het beheer van Build Number volledig en elimineert menselijke fouten bij de voorbereiding van een release.

Automatische increment van Build Number

Automatische increment van Build Number is standaardpraktijk in moderne CI/CD-pijplijnen. Handmatige verhoging van het buildnummer leidt tot fouten en conflicten bij publicatie.

GitHub Actions, GitLab CI en Jenkins bieden ingebouwde variabelen met het buildnummer. Deze variabelen worden gebruikt in Gradle- of Xcode-scripts voor automatische invulling van Build Number.

Volgens GitLab CI Documentation (2025) garandeert de variabele CI_PIPELINE_IID een uniek nummer voor elke pijplijn, wat ideaal is voor gebruik als Build Number.

Configureer automatische increment op CI/CD-niveau — dit elimineert de noodzaak om Build Number handmatig te wijzigen bij elke commit naar de releasetak.

Populaire automatiseringstools

GitHub Actions ondersteunt de ingebouwde variabele run_number, die automatisch verhoogt bij elke pijplijnuitvoering. De waarde kan aan Gradle worden doorgegeven via versionCode.

Jenkins gebruikt de variabele BUILD_NUMBER, die beschikbaar is in alle buildfasen. Voor Xcode-projecten voert Jenkins agvtool uit met dit nummer.

Kies de tool die is geïntegreerd in uw technologiestack om extra configuratie te minimaliseren.

Build Number en Version Name

Build Number en Version Name werken als een paar: de eerste — voor machines, de tweede — voor mensen. Build Number zorgt voor technische uniciteit, Version Name — voor voor de gebruiker begrijpelijke semantiek.

In Android zijn deze twee parameters onafhankelijk: versionCode kan stijgen zonder wijziging van versionName (bijvoorbeeld om een buildfout te corrigeren). In iOS is CFBundleVersion ook niet gekoppeld aan CFBundleShortVersionString.

Volgens Stack Overflow Developer Survey (2024) gebruikt 82% van de teams automatische increment van Build Number, maar slechts 45% automatiseert de update van Version Name — dit is een van de veelvoorkomende oorzaken van fouten bij releases.

Verhoog altijd Build Number bij elke build, zelfs als Version Name niet verandert — dit garandeert correcte werking van het updatemechanisme in app-winkels.

Best practices voor Build Number

Begin versionCode bij 1 en verhoog met 1 voor elke build. Gebruik voor iOS een analoge aanpak met CFBundleVersion. Vermijd samengestelde nummers als er geen strikte noodzaak is — een eenvoudig opeenvolgend nummer is gemakkelijker te volgen.

Koppel Build Number aan het buildnummer van het CI/CD-systeem — dit vereenvoudigt het traceren van een fout naar een specifieke commit. Git-tag met het buildnummer en versie is de beste praktijk voor releasebeheer.

Voorbeelden van Build Number-configuratie

Codevoorbeelden tonen hoe u automatische increment van Build Number op beide platforms configureert.

versionCode in Gradle met CI-variabele

In Android kan versionCode worden ingesteld via een CI/CD-omgevingsvariabele. Als de variabele niet is ingesteld, wordt de standaardwaarde gebruikt.

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

versionCode krijgt de waarde uit de CI/CD-variabele, wat de uniciteit van het nummer voor elke build in de pijplijn garandeert.

CFBundleVersion-increment via agvtool

In iOS wordt voor automatische verhoging van Build Number agvtool gebruikt, dat is ingebouwd in Xcode Command Line Tools.

# Buildnummer verhogen met 1
xcrun agvtool next-version -all

# Specifiek buildnummer instellen
xcrun agvtool new-version -all "3.0.1"

De vlag -all werkt de versie bij in alle projecttargets, wat de synchronisatie van waarden tussen de hoofdapp en extensies garandeert.

Fastlane voor automatisering

Fastlane — een populair hulpmiddel voor het automatiseren van mobiele app-builds. De plugin increment_build_number verhoogt automatisch Build Number.

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

Fastlane integreert met elk CI/CD-systeem en ondersteunt zowel Android- als iOS-projecten.