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, де патч-версія опускається для спрощення сприйняття.

Календарне версіонування (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.