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.