Version Name: a paraméter lényege és beállítása

Mi az a Version Name

Version Name — egy szemantikus karakterlánc, amely azonosítja az alkalmazás kiadását a felhasználó számára. A technikai build-azonosítóktól eltérően ez a paraméter jelentéssel bír: alapján a felhasználó megítéli, mennyire különbözik az új frissítés az előzőtől.

A Version Name az alkalmazáskártyán jelenik meg a Google Play-ben és App Store-ban, az „Alkalmazásról” részben az eszközön, valamint a rendszer frissítési párbeszédeiben. A fejlesztők a projekt konfigurációs fájljaiban adják meg a kiadási verzió elkészítése előtt.

A Semantic Versioning 2.0 (2023) szerint a Major.Minor.Patch formátumot a mobilalkalmazások 78%-a használja. A major verzió az API inkompatibilis változásainál, a minor — funkciók hozzáadásánál, a patch — hibajavításoknál változik.

Használja a Version Name-t a felhasználóval való kommunikációhoz: azonnal meg kell értenie, mekkora frissítést kap — major, minor vagy javító jellegűt.

A szemantikus verzió szerkezete

Szemantikus verzió három pontokkal elválasztott számból áll: Major.Minor.Patch. Mindegyik összetevő az alkalmazás változásainak egy adott szintjéért felelős.

A major verzió (Major) gyökeres változtatásoknál nő, amelyek megtörik a visszafelé kompatibilitást. A minor verzió (Minor) új funkciókat ad hozzá a meglévők megzavarása nélkül. A Patch csak hibajavításokat tartalmaz.

Például a 3.2.1 verzió jelenti: harmadik major verzió, második minor frissítés, első patch. Ez a rendszer érthető mind a fejlesztők, mind a felhasználók számára.

Hol jelenik meg a Version Name

Version Name látható a felhasználó számára néhány kulcsfontosságú helyen. Az alkalmazásáruházban az alkalmazáskártya fejlécében és a frissítési listában jelenik meg. Az eszközön — a rendszerbeállítások „Alkalmazásról” részében.

A Google Play-ben a Version Name az alkalmazás neve alatt jelenik meg, és befolyásolja a felhasználó frissítési döntését. Az App Store-ban a verzió karakterlánc ugyanazon a helyen jelenik meg az alkalmazás oldalának megtekintésekor.

Az Apptentive (2024) kutatása szerint a felhasználók 67%-a ellenőrzi az alkalmazás verzióját frissítés előtt, és az érthető szemantika 23%-kal növeli a telepítési konverziót.

Version Name Android rendszeren

Android rendszeren a Version Name-t a versionName paraméterrel állítjuk be a build.gradle fájlban (modul szinten). Ez a paraméter egy karakterlánc, és bármilyen karaktert tartalmazhat, beleértve pontokat, kötőjeleket és betűket.

A paramétert az android.defaultConfig blokkon belül deklaráljuk a kötelező versionCode paraméterrel együtt. Az Android nem ír elő korlátozásokat a karakterlánc formátumára, de a Google Play a szemantikus formátum használatát ajánlja.

A Android Developers (2025) szerint a Google Play a versionName-t az áruház felületén való megjelenítéshez használja, de programozottan nem elemzi a tartalmát — csak a versionCode befolyásolja a frissítési logikát.

Adja meg a Version Name-t Major.Minor.Patch formátumban, és szinkronizálja a verziókezelő rendszerben lévő tag-gel a kiadás egyértelmű azonosításához.

A versionName jellemzői Gradle-ben

Gradle lehetővé teszi a versionName statikus beállítását a build.gradle-ben vagy dinamikus beállítását build szkripteken keresztül. A dinamikus generálás hasznos az automatikus éjszakai build-ekhez és CI/CD pipeline-okhoz.

A build.gradle-ben környezeti változókat, parancssori paramétereket vagy shell szkriptek hívásait használhatja a versionName kialakításához. A tipikus megközelítés a verzió beolvasása a version.properties fájlból.

Ez a rugalmasság lehetővé teszi a csapatok számára, hogy automatizálják a verziózási folyamatot és kiküszöböljék az emberi tényezőt a kiadás előkészítésénél.

Version Name iOS rendszeren

iOS rendszeren a Version Name-t a CFBundleShortVersionString kulccsal állítjuk be az Info.plist fájlban. Ez kötelező paraméter az alkalmazás App Store-ban történő közzétételéhez, és szigorúan karakterláncként van típusozva.

Az Android-tól eltérően az App Store Connect ellenőrzi a Version Name formátumát, és megköveteli a pontokkal elválasztott számok mintájának való megfelelt. A karakterlánc maximális hossza 18 karakter, és a verzió minden összetevője nem haladhatja meg a 255-öt.

Az Apple Developer Documentation (2025) szerint a CFBundleShortVersionString-t az App Store használja a verzió megjelenítéséhez az áruház felületében és a rendszer párbeszédeiben a felhasználó eszközén.

A build App Store Connect-be történő feltöltésekor győződjön meg arról, hogy a Version Name megegyezik a marketing anyagokban feltüntetett verzióval — ez egyszerűsíti a felhasználókkal való kommunikációt.

Integráció az Xcode-dal

Xcode grafikus felületet biztosít a Version Name módosításához a target beállításaiban. A „Marketing Version” mező a General fülen található az Identity részben. A változtatások automatikusan mentődnek az Info.plist-ben.

Az automatizáláshoz használhat build szkripteket az Xcode Build Phases-ben vagy az agvtool (Apple Generic Version Tool) segédprogramot. Az agvtool lehetővé teszi a verziók kezelését parancssorból és integrálódik a CI/CD-vel.

Ez a megközelítés különösen kényelmes a fastlane vagy Jenkins használata esetén az alkalmazások automatikus építéséhez és szállításához.

A Version Name és a Build Number közötti különbségek

Version Name és a Build Number különböző feladatokat látnak el a fejlesztési folyamatban. A Version Name egy felhasználói karakterlánc, a Build Number pedig egy belső numerikus azonosító, amely egyedileg azonosítja minden egyes build-et.

A Build Number (versionCode Android rendszeren, CFBundleVersion iOS rendszeren) kötelezően nő minden új build-del, és az alkalmazásáruházak használják annak meghatározására, melyik verzió az újabb. A Version Name változatlan maradhat ugyanazon verzió több build-je esetén.

A Google Play Policy (2025) szerint két azonos versionCode-dal rendelkező alkalmazás ugyanannak a verziónak minősül — a versionCode-nak egyedinek kell lennie minden APK-hoz. A Version Name nem vesz részt ebben az ellenőrzésben.

Mindig növelje a Build Number-t minden build-nél, és csak a funkcionalitás változásakor módosítsa a Version Name-t — ez megakadályozza a konfliktusokat a közzététel során.

Hogyan válasszuk ki a Version Name-t

A Version Name kiválasztása a csapat verziózási stratégiájától függ. A legelterjedtebb megközelítés a szemantikus verziózás (SemVer), de léteznek alternatív sémák is, mint a naptári verziózás vagy a kiadási dátum szerinti verziózás.

Semantic Versioning 2.0 a Major.Minor.Patch formátumot ajánlja opcionális pre-release utótagokkal. Mobilalkalmazásoknál a Major.Minor séma is népszerű, ahol a patch elmarad az érzékelés egyszerűsítésére.

A naptári verziózás (CalVer) a kiadás dátumát használja verziószámként — például 25.06 (év és hónap). Ez a megközelítés a gyakori kiadású alkalmazásoknál kényelmes, ahol a szemantikának nincs jelentősége.

Ajánlások a séma kiválasztásához

Szemantikus verziózás alkalmas a nyilvános API-val rendelkező alkalmazásokhoz, ahol fontos a visszafelé kompatibilitás. A felhasználók és az integrátorok megértik, milyen változtatásokat várhatnak a frissítésnél.

Naptári verziózás azoknál az alkalmazásoknál választandó, ahol a felhasználó számára a kiadás frissessége fontos, nem a változások mérete. Például hírösszeállítók vagy időjárás alkalmazások.

Hibrid séma egyesíti mindkét megközelítést: Major.Minor.RC, ahol az RC a build száma egy adott kiadási jelölt számára. Ez a séma az aktív béta tesztelésnél kényelmes.

Példák a Version Name beállítására

Kódpéldák alább megmutatják, hogyan kell beállítani a Version Name-t Android és iOS rendszeren. Androidhoz Gradle-t, iOS-hez Xcode Build Settings-et használunk agvtool segédprogrammal.

A versionName beállítása Android rendszeren

Android rendszeren a verziót az app/build.gradle fájlban állítjuk be a defaultConfig blokkon belül. A versionName paraméter karakterlánc értéket fogad el.

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

versionName külső fájlból is olvasható, vagy dinamikusan is generálható Gradle Script segítségével.

A versionName dinamikus generálása

Dinamikus verzió a CI/CD rendszer környezeti változóiból képződik. Ez garantálja, hogy minden build megkapja a megfelelő verziószámot.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Ez a megközelítés automatizálja a verziózást és kiküszöböli a build és a repóban lévő tag közötti eltérés kockázatát.

A CFBundleShortVersionString beállítása iOS rendszeren

iOS rendszeren a verziót Xcode-on keresztül vagy parancssorból az agvtool segédprogrammal állíthatja be.

# Marketingverzió beállítása
xcrun agvtool new-marketing-version 2.1.0

# Aktuális verzió beolvasása
xcrun agvtool what-marketing-version

agvtool automatikusan frissíti az Info.plist-et és szinkronizálja a verziót az Xcode projekt összes target-je között.