Version Name: същност, значение на параметъра и настройка

Какво е Version Name

Version Name е семантичен низ, който идентифицира версията на приложението за потребителя. За разлика от техническите идентификатори на сборките, този параметър носи смислова натовареност: по него потребителят оценява колко се различава новата актуализация от предишната.

Version Name се показва в картата на приложението в Google Play и App Store, в раздела „За приложението“ на устройството, както и в системните диалози за обновяване. Разработчиците го задават в конфигурационните файлове на проекта преди изграждането на финалната версия.

Според Semantic Versioning 2.0 (2023), форматът Major.Minor.Patch се използва в 78% от мобилните приложения. Основната версия се променя при несъвместими промени в API, второстепенната — при добавяне на функционалност, а корекцията — при отстраняване на грешки.

Използвайте Version Name за комуникация с потребителя: той трябва веднага да разбере колко голяма актуализация му се предлага — основна, второстепенна или коригираща.

Структура на семантичната версия

Семантичната версия се състои от три числа, разделени с точки: Major.Minor.Patch. Всяка от тези компоненти отговаря за определено ниво на промените в приложението.

Основната версия (Major) се увеличава при въвеждане на кардинални промени, които нарушават обратната съвместимост. Второстепенната версия (Minor) добавя нова функционалност, без да засяга съществуващата. Корекцията (Patch) съдържа само отстраняване на грешки.

Например версията 3.2.1 означава: трета основна версия, второ второстепенно обновление, първа корекция. Такава система е разбираема и за разработчиците, и за потребителите.

Къде се показва Version Name

Version Name е видим за потребителя на няколко ключови места. В магазина за приложения се показва в заглавието на картата на приложението и в списъка с обновления. На устройството — в системните настройки в раздела „За приложението“.

В Google Play Version Name се показва под името на приложението и влияе върху решението на потребителя за обновяване. В App Store низът на версията се показва на същото място при преглед на страницата на приложението.

Според проучването на Apptentive (2024), 67% от потребителите проверяват версията на приложението преди обновяване, а разбираемата семантика увеличава конверсията в инсталиране с 23%.

Version Name в Android

В Android Version Name се задава чрез параметъра versionName във файла build.gradle (на ниво модул). Този параметър е низ и може да съдържа произволни символи, включително точки, тирета и букви.

Параметърът се декларира в блока android.defaultConfig заедно със задължителния параметър versionCode. Android не налага ограничения върху формата на низа, но Google Play препоръчва използването на семантичен формат.

Според Android Developers (2025), Google Play използва versionName за показване в интерфейса на магазина, но не анализира съдържанието му програмно — само versionCode влияе върху логиката на обновяване.

Задавайте Version Name във формат Major.Minor.Patch и го синхронизирайте с тага в системата за контрол на версиите за еднозначна идентификация на версията.

Особености на versionName в Gradle

Gradle позволява да задавате versionName статично в build.gradle или динамично чрез скриптове за изграждане. Динамичната генерация е полезна за автоматични нощни сборки и CI/CD тръбопроводи.

В build.gradle могат да се използват променливи на средата, параметри на командния ред или извиквания на shell скриптове за формиране на versionName. Типичен подход е четенето на версията от файла version.properties.

Такава гъвкавост позволява на екипите да автоматизират процеса на версиониране и да изключат човешкия фактор при подготовката на версията.

Version Name в iOS

В iOS Version Name се задава чрез ключа CFBundleShortVersionString във файла Info.plist. Това е задължителен параметър за публикуване на приложението в App Store и е строго типизиран като низ.

За разлика от Android, App Store Connect проверява формата на Version Name и изисква съответствие с шаблона от числа, разделени с точки. Максималната дължина на низа е 18 символа, а всяка компонента на версията не може да надвишава 255.

Според Apple Developer Documentation (2025), CFBundleShortVersionString се използва от App Store за показване на версията в интерфейса на магазина и в системните диалози на устройството на потребителя.

При качване на сборката в App Store Connect се уверете, че Version Name съответства на версията, посочена в маркетинговите материали — това опростява комуникацията с потребителите.

Интеграция с Xcode

Xcode предоставя графичен интерфейс за промяна на Version Name в настройките на таргета. Полето „Marketing Version“ се намира в раздела General, секция Identity. Промените автоматично се записват в Info.plist.

За автоматизация могат да се използват скриптове за изграждане в Xcode Build Phases или помощната програма agvtool (Apple Generic Version Tool). agvtool позволява управление на версиите от командния ред и се интегрира в CI/CD.

Такъв подход е особено удобен при използване на fastlane или Jenkins за автоматично изграждане и доставка на приложения.

Разлики между Version Name и Build Number

Version Name и Build Number изпълняват различни задачи в процеса на разработка. Version Name е потребителски низ, а Build Number е вътрешен числов идентификатор, който уникално идентифицира всяка сборка.

Build Number (versionCode в Android, CFBundleVersion в iOS) задължително се увеличава с всяка нова сборка и се използва от магазините за приложения, за да се определи коя версия е по-нова. Version Name може да остане непроменен за няколко сборки на една версия.

Според Google Play Policy (2025), две приложения с еднакъв versionCode се считат за една и съща версия — versionCode трябва да е уникален за всеки APK. Version Name не участва в тази проверка.

Винаги увеличавайте Build Number при всяка сборка и променяйте Version Name само при промяна на функционалността — това предотвратява конфликти при публикуването.

Как да изберете Version Name

Изборът на Version Name зависи от стратегията за версиониране на екипа. Най-разпространеният подход е семантичното версиониране (SemVer), но съществуват и алтернативни схеми, като календарно версиониране или версиониране по дата на пускане.

Semantic Versioning 2.0 препоръчва формат Major.Minor.Patch с опционални pre-release суфикси. За мобилни приложения е популярна и схемата Major.Minor, при която patch версията се пропуска за опростяване на възприятието.

Календарното версиониране (CalVer) използва датата на пускане като номер на версията — например 25.06 (година и месец). Този подход е удобен за приложения с чести пускания, където семантиката няма значение.

Препоръки за избор на схема

Семантичното версиониране е подходящо за приложения с публичен API, където обратната съвместимост е важна. Потребителите и интеграторите разбират какви промени да очакват при обновяване.

Календарното версиониране се избира за приложения, където на потребителя е важна свежестта на версията, а не обемът на промените. Например новинарски агрегатори или приложения за времето.

Хибридната схема обединява двата подхода: Major.Minor.RC, където RC е номерът на сборката за конкретен кандидат за версия. Такава схема е удобна при активно бета тестване.

Примери за настройка на Version Name

Примерите с код по-долу показват как се задава Version Name в Android и iOS. За Android се използва Gradle, а за iOS — Xcode Build Settings с agvtool.

Настройка на versionName в Android

В Android версията се задава във файла app/build.gradle в блока defaultConfig. Параметърът versionName приема стойност под формата на низ.

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

versionName може също да се чете от външен файл или да се генерира динамично с помощта на Gradle Script.

Динамична генерация на versionName

Динамичната версия се формира от променливите на средата на CI/CD системата. Това гарантира, че всяка сборка получава коректен номер на версията.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Такъв подход автоматизира версионирането и изключва риска от несъответствие между сборката и тага в хранилището.

Настройка на CFBundleShortVersionString в iOS

В iOS версията може да се зададе чрез Xcode или от командния ред чрез agvtool.

# Задаване на маркетингова версия
xcrun agvtool new-marketing-version 2.1.0

# Четене на текущата версия
xcrun agvtool what-marketing-version

agvtool автоматично обновява Info.plist и синхронизира версията между всички таргети в проекта на Xcode.