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 не змінюється, код збільшується
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 для різних конфігурацій: демо-версія, окрема версія для планшетів. Якщо в проєкті використовуються flavors, фінальний Version Code складається з базового числа та flavour-специфічного інкременту. 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 його ще не бачив.

• Монотонний інкремент — кожна збірка в треку має Version Code більший за попередню в цьому ж треку
• Cross-track awareness — при просуванні між треками Version Code збільшується послідовно
• Внутрішнє тестування — трек для внутрішнього тестування використовує ті ж правила монотонності
• 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, з якого всі треки читають поточне значення.