Marketing Version: какво е това, разлика от Build Number и инсталиране

Какво е Marketing Version

Marketing Version — е семантичен низ, който представя версията на приложението за крайния потребител. В iOS се задава с ключ CFBundleShortVersionString, в Android — с параметър versionName.

Терминът „Marketing Version" се използва официално в Xcode: в интерфейса за настройки на target полето се нарича „Marketing Version", а в Info.plist съответства на CFBundleShortVersionString. В Android аналогът е versionName, въпреки че терминът се използва по-рядко.

Според Apple Developer Documentation (2025), Marketing Version трябва да се състои от максимум три числа, разделени с точки, без интервали и специални символи. Всяко число не трябва да надвишава 255.

Изберете Marketing Version така, че да отразява значимостта на промените: основни актуализации за радикални промени, второстепенни — за нова функционалност.

Разлика от вътрешния Build Number

Marketing Version се различава принципно от Build Number по предназначение: първият информира потребителя, вторият — идентифицира компилацията за магазина. Build Number може да расте без промяна на Marketing Version.

Например, при коригиране на критична грешка в пусната версия, екипът може да прекомпилира приложението със същата Marketing Version (1.2.0), но с увеличен Build Number (от 15 на 16). Потребителят ще види същата версия, но магазинът ще разбере, че компилацията е по-нова.

Тази гъвкавост позволява на разработчиците да пускат корекции, без да уведомяват потребителите за промяна на версията.

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

Marketing Version се показва на няколко ключови точки на взаимодействие на потребителя с приложението. В магазина за приложения се вижда в картата на приложението, в описанието на актуализацията и в историята на версиите.

На устройството Marketing Version се показва в системните настройки (раздел „За приложението" или „Приложения"), в диалоговите прозорци за актуализация чрез App Store или Google Play, както и вътре в самото приложение на екрана „За програмата".

Разбираемата Marketing Version помага на потребителя да прецени актуалността на инсталираната версия и да вземе решение за актуализация.

Marketing Version на iOS

На iOS Marketing Version се задава в Xcode чрез полето „Marketing Version" в раздела General на настройките на target. Стойността се запазва в Info.plist като CFBundleShortVersionString.

Форматът на версията е строго регламентиран от Apple: низът трябва да съдържа от едно до три числа, разделени с точки (например 1, 1.2 или 1.2.3). Максимална дължина — 18 знака. Всяко число не надвишава 255.

Според Apple App Store Review Guidelines (2025), App Store Connect не позволява качване на компилация, ако Marketing Version се различава от предходната публикувана версия с повече от една основна или второстепенна стойност — това защитава потребителите от пропуснати актуализации.

Използвайте agvtool за управление на Marketing Version от командния ред — това опростява интеграцията с CI/CD системи и гарантира синхронизация с Build Number.

Marketing Version на Android

На Android Marketing Version се задава с параметър versionName във файла build.gradle. За разлика от iOS, Android не налага строги ограничения върху формата на низа за версия.

versionName може да съдържа всякакви символи: букви, цифри, тирета и точки. Google Play показва този низ в картата на приложението и в списъка с актуализации, но не го проверява за съответствие с никакъв шаблон.

Въпреки това Google Play препоръчва да се придържате към семантичния формат Major.Minor.Patch за единообразие. Това опростява възприемането на версията от потребителите и позволява автоматизиран анализ на актуализациите.

Посочете versionName, който ясно отразява типа на версията — основна актуализация, второстепенна или корекция. Това помага на потребителите бързо да преценят значимостта на промените.

Динамично генериране на versionName

versionName на Android може да се генерира динамично на базата на Git тагове или CI/CD променливи. Това опростява процеса на версиониране и елиминира несъответствията между хранилището и компилацията.

Типичен подход — четене на Git таг (например v2.1.0) и използване на стойността му като versionName. Ако таг липсва, версията може да се генерира на базата на дата и номер на commit.

Този подход гарантира, че versionName винаги съответства на състоянието на изходния код и не изисква ръчно обновяване.

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

Marketing Version и Build Number — са два независими параметъра, които решават различни задачи. Marketing Version информира потребителя, а Build Number технически идентифицира компилацията.

Ключовата разлика — уникалност. Build Number трябва да бъде уникален за всяка компилация. Marketing Version може да се повтаря: няколко компилации на една и съща версия имат еднакъв Marketing Version, но различни Build Number.

Според Google Play Policy (2025), ако се качат два APK с еднакъв Marketing Version, но различен Build Number, Google Play ще приеме и двата като различни компилации на една и съща версия. За App Store важи подобно правило.

Запомнете: Build Number — за машини, Marketing Version — за хора. Автоматизирайте първото и внимателно планирайте второто.

Стратегии за версиониране

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

Семантична версия (SemVer) използва формат Major.Minor.Patch и строго определя кога кой компонент да се увеличи. Тя е идеална за приложения с публично API и сложна интеграция.

Според semver.org (2023), версия 2.0.0 на спецификацията SemVer се използва в 89% от open-source мобилни проекти и се поддържа от всички мениджъри на пакети.

Календарно версиониране

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

CalVer не носи информация за значимостта на промените, но отлично показва свежестта на версията. Потребителят веднага разбира, че версия 25.06 е по-нова от 25.03.

Изберете календарно версиониране, ако приложението ви се актуализира често и за потребителите актуалността на данните е по-важна от обема на промените.

Препоръки за избор

За MVP и стартъпи е подходяща проста семантична версия без корекция (Major.Minor). За зрели продукти с дългосрочна поддръжка — пълна SemVer. За приложения с непрекъснати пускания — CalVer.

Никога не използвайте датата като Build Number — това може да доведе до конфликти при няколко компилации на ден. Build Number трябва да бъде последователен или съставен, но винаги монотонно нарастващ.

Грешки при избора на Marketing Version

Типична грешка — пропускане на компонент на версията при преминаване към нова основна линия. Например след версия 1.9.9 следващата трябва да бъде 2.0.0, а не 1.10.0. Това нарушава семантиката и обърква потребителите.

Друг чест проблем — несъответствие на Marketing Version в кода и в магазина за приложения. Винаги проверявайте, че versionName в build.gradle съвпада с версията, посочена в Google Play Console или App Store Connect, преди да изпратите компилацията за преглед.

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

Примери за код показват как да зададете Marketing Version на двете платформи и да автоматизирате нейното обновяване.

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

В Android versionName се задава в build.gradle. Стойността може да бъде статична или да се чете от променлива на средата.

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

// Четене на версия от Git таг
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

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

Управление на Marketing Version в Xcode

В iOS Marketing Version се задава чрез Xcode или agvtool. Командата по-долу задава нова маркетингова версия.

# Задаване на Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# Автоматично увеличение
xcrun agvtool next-marketing-version

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

Fastlane за двете платформи

Fastlane позволява управление на Marketing Version на двете платформи от един скрипт, което опростява поддръжката на междуплатформени проекти.

# Задаване на маркетингова версия
increment_version_number(
    version_number: "2.1.0"
)

# Автоматично увеличение на второстепенна версия
increment_version_number(
    bump_type: "minor"
)

Fastlane работи на двете платформи и се поддържа от повечето CI/CD услуги.