Marketing Version: що це таке, відмінність від Build Number та налаштування

Що таке Marketing Version

Marketing Version — це семантичний рядок, який представляє версію застосунку для кінцевого користувача. В iOS вона задається ключем CFBundleShortVersionString, в Android — параметром versionName.

Термін «Marketing Version» офіційно використовується в Xcode: в інтерфейсі налаштувань таргета поле називається «Marketing Version», а в Info.plist воно відповідає CFBundleShortVersionString. На Android аналогом є versionName, хоча термін використовується рідше.

За даними документації Apple Developer (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 налаштувань таргета. Значення зберігається в 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. Якщо тег відсутній, можна згенерувати версію на основі дати та номера коміту.

Такий підхід гарантує, що 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 і синхронізує версію між усіма таргетами Xcode проекту.

Fastlane для обох платформ

Fastlane дозволяє керувати Marketing Version на обох платформах з одного скрипта, що спрощує підтримку крос-платформних проектів.

# Встановлення маркетингової версії
increment_version_number(
    version_number: "2.1.0"
)

# Автоматичне збільшення мінорної версії
increment_version_number(
    bump_type: "minor"
)

Fastlane працює на обох платформах і підтримується більшістю CI/CD сервісів.