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 при всяко предаване в release клон
• Timestamp формат — 20260703 за дневни изграждания, 2026070301 за няколко на ден
• SemVer в числа — 100010000 за версия 1.1.0 (major 1, minor 1, patch 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, Име: $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 все още не го е видял.

• 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, от който всички трекове четат текущата стойност.