Version Code: что это, числовой идентификатор и обновления

Что такое Version Code в Android

Version Code — это целое число типа Integer, которое присваивается каждой сборке Android-приложения. В отличие от Version Name, Version Code не отображается пользователю и используется исключительно операционной системой и Google Play для сравнения версий при установке обновлений.

Формат Version Code

Version Code должен быть целым положительным числом в диапазоне от 1 до 2100000000. Каждая последующая сборка обязана иметь Version Code строго больше предыдущей. Если разработчик выпустил сборку с Version Code 5, следующая публикация может использовать 6, 7 или любое число больше 5, но не 4 и не 5 повторно.

История возникновения

Google ввёл разделение на Version Code и Version Name с выходом Android SDK в 2007 году. Version Code был задуман как машинный идентификатор для автоматического сравнения версий, в то время как Version Name — как человекочитаемая метка. Такое разделение позволяет разработчику называть версию как угодно, сохраняя строгий порядок обновлений через числовой код.

Как работает версионирование через Version Code

Механизм сравнения Version Code встроен в операционную систему Android и магазин Google Play. При каждой публикации Google Play проверяет, что Version Code новой сборки больше кода установленной версии. Если условие не выполняется, публикация отклоняется с ошибкой.

Процесс проверки обновления

Когда устройство обращается к Google Play для проверки обновлений, сервер сравнивает Version Code установленного приложения с максимальным доступным в магазине. Если код на сервере больше — запускается загрузка и установка обновления. Пользователь видит Version Name, указанный разработчиком, но решение об обновлении принимается на основе Version Code.

Инкремент Version Code

Разработчики применяют разные стратегии инкремента Version Code. Простейшая — увеличение на 1 при каждой сборке. Для CI/CD-пайплайнов часто используют timestamp или номер сборки: 2026070301 (год-месяц-день-номер). Важно, чтобы код монотонно возрастал и не повторялся между разными сборками и треками Google Play.

• Монотонный инкремент — увеличение на 1 при каждом коммите в релизную ветку
• Timestamp-формат — 20260703 для ежедневных сборок, 2026070301 для нескольких в день
• SemVer в числах — 100010000 для версии 1.1.0 (мажор 1, минор 1, патч 0)
• Номер билда — использование BUILD_NUMBER из CI-системы (Jenkins, GitHub Actions)

Отличия Version Code от Version Name

Version Code и Version Name — два независимых поля в build.gradle, которые выполняют разные функции. Version Code — внутренний идентификатор для системы, Version Name — маркетинговая метка для пользователя. Они могут изменяться независимо друг от друга.

Version Name для пользователя

Version Name — это строка, которая отображается в настройках приложения, в Google Play и в диалогах обновлений. Разработчик может указать любой формат: 1.0.0, 2.3.1-beta, 3.0-rc1. Для сравнения строковых версий Version Name не используется — Google Play всегда опирается на Version Code.

Сценарии расхождения

Возможна ситуация, когда Version Code увеличивается, а Version Name остаётся прежним. Например, если разработчик исправляет критический баг в hotfix-сборке без изменения функциональности. Version Name остаётся 2.0.0, а Version Code меняется с 5 на 6. Google Play корректно обработает такое обновление.

// Пример: version name не меняется, code увеличивается
android {
    defaultConfig {
        versionCode 6  // Было 5 — hotfix без новых функций
        versionName "2.0.0"  // Не изменилось
    }
}

// Проверка версий в runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Настройка Version Code в build.gradle

Настройка Version Code выполняется в файле build.gradle модуля приложения. Поле versionCode принимает целое число и входит в блок defaultConfig. Для разных flavour-сборок можно задавать собственные значения через поле versionCode в конфигурации продукта.

Базовая конфигурация

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Product flavors позволяют использовать разные Version Code для различных конфигураций: demo-версия, отдельная версия для планшетов. Если в проекте используются flavors, финальный Version Code складывается из базового числа и flavour-specific инкремента. Google Play отслеживает каждую комбинацию независимо.

Автоматизация инкремента через CI

В CI/CD-пайплайнах (GitHub Actions, GitLab CI, Jenkins) Version Code часто генерируется автоматически на основе номера билда или даты. Это исключает человеческую ошибку при ручном обновлении. Скрипт считывает текущий Version Code из build.gradle, увеличивает его и записывает обратно перед началом сборки.

// Автоматический инкремент Version Code
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Особенности Version Code для публикации в Google Play

Google Play имеет строгие правила для Version Code при публикации и обновлении приложений. Нарушение этих правил приводит к отклонению сборки или невозможности выпустить обновление. Разработчику необходимо понимать ограничения и стратегии управления кодом на всех этапах жизненного цикла.

Правило монотонного возрастания

Google Play не позволяет загрузить APK или AAB, Version Code которого меньше или равен текущему опубликованному. Это правило действует для каждого трека (production, beta, alpha) независимо. Если в production загружена сборка с Version Code 10, а в alpha — с кодом 5, alpha-трек можно обновить до 6, 7, 8 или 9, но production остаётся на 10.

Миграция между треками

При продвижении сборки из alpha в beta, а затем в production Version Code должен возрастать на каждом этапе. Если alpha-версия имеет код 10, beta может использовать 11, а production — 12. Нельзя выкатить в production сборку с кодом 10, если alpha уже использует 10, даже если production его ещё не видел.

• Monotonous increment — каждая сборка в треке имеет Version Code больше предыдущей в этом же треке
• Cross-track awareness — при продвижении между треками Version Code увеличивается последовательно
• Internal testing — трек для внутреннего тестирования использует те же правила монотонности
• Multiple APKs — старый формат публикации требовал уникального Version Code для каждого APK

Ошибки при указании Version Code

Самая частая ошибка — совпадение Version Code в разных сборках, загруженных в один трек. Google Play выдаёт ошибку APK_VERSION_CODE_ALREADY_EXISTS. Другая ошибка — превышение максимального значения 2100000000, что приводит к сбою при компиляции. Для избежания конфликтов используйте автоматическую генерацию кода в CI-системе с привязкой к номеру билда или дате сборки.

Также разработчики часто совершают ошибку, не увеличивая Version Code при сборке hotfix-релиза для альтернативного трека. Если production имеет код 15, а alpha-трек остался на 14, при продвижении alpha в production Google Play отклонит сборку, так как её код меньше текущего production. Следите за монотонностью кода во всех треках одновременно — для этого удобно использовать единый файл version.properties, из которого все треки читают текущее значение.