Version Code: co to jest, numeryczny identyfikator i aktualizacje

Co to jest Version Code w Android

Version Code — to liczba całkowita typu Integer, przypisywana każdej kompilacji aplikacji Android. W przeciwieństwie do Version Name, Version Code nie jest wyświetlany użytkownikowi i jest używany wyłącznie przez system operacyjny i Google Play do porównywania wersji podczas instalacji aktualizacji.

Format Version Code

Version Code musi być dodatnią liczbą całkowitą w zakresie od 1 do 2100000000. Każda kolejna kompilacja musi mieć Version Code ściśle większy od poprzedniej. Jeśli programista wydał kompilację z Version Code 5, następna publikacja może użyć 6, 7 lub dowolnej liczby większej niż 5, ale nie 4 ani nie 5 ponownie.

Historia powstania

Google wprowadził podział na Version Code i Version Name wraz z wydaniem Android SDK w 2007 roku. Version Code został zaprojektowany jako maszynowy identyfikator do automatycznego porównywania wersji, podczas gdy Version Name — jako czytelna dla człowieka etykieta. Taki podział pozwala programiście nazywać wersję dowolnie, zachowując ścisły porządek aktualizacji przez numeryczny kod.

Jak działa wersjonowanie przez Version Code

Mechanizm porównywania Version Code jest wbudowany w system operacyjny Android i sklep Google Play. Przy każdej publikacji Google Play sprawdza, czy Version Code nowej kompilacji jest większy od kodu zainstalowanej wersji. Jeśli warunek nie jest spełniony, publikacja jest odrzucana z błędem.

Proces sprawdzania aktualizacji

Gdy urządzenie łączy się z Google Play w celu sprawdzenia aktualizacji, serwer porównuje Version Code zainstalowanej aplikacji z maksymalnym dostępnym w sklepie. Jeśli kod na serwerze jest większy — uruchamiane jest pobieranie i instalacja aktualizacji. Użytkownik widzi Version Name podany przez programistę, ale decyzja o aktualizacji jest podejmowana na podstawie Version Code.

Inkrement Version Code

Programiści stosują różne strategie inkrementacji Version Code. Najprostsza — zwiększenie o 1 przy każdej kompilacji. Dla potoków CI/CD często używają timestamp lub numer kompilacji: 2026070301 (rok-miesiąc-dzień-numer). Ważne, aby kod monotonicznie wzrastał i nie powtarzał się między różnymi kompilacjami i ścieżkami Google Play.

• Inkrement monotoniczny — zwiększenie o 1 przy każdym commicie do gałęzi release
• Format timestamp — 20260703 dla codziennych kompilacji, 2026070301 dla kilku dziennie
• SemVer w liczbach — 100010000 dla wersji 1.1.0 (major 1, minor 1, patch 0)
• Numer kompilacji — użycie BUILD_NUMBER z systemu CI (Jenkins, GitHub Actions)

Różnice między Version Code a Version Name

Version Code i Version Name — dwa niezależne pola w build.gradle, które pełnią różne funkcje. Version Code to wewnętrzny identyfikator dla systemu, Version Name to etykieta marketingowa dla użytkownika. Mogą się zmieniać niezależnie od siebie.

Version Name dla użytkownika

Version Name — to ciąg znaków, który jest wyświetlany w ustawieniach aplikacji, w Google Play i w oknach dialogowych aktualizacji. Programista może podać dowolny format: 1.0.0, 2.3.1-beta, 3.0-rc1. Do porównywania wersji tekstowych Version Name nie jest używany — Google Play zawsze opiera się na Version Code.

Scenariusze rozbieżności

Możliwa jest sytuacja, gdy Version Code wzrasta, a Version Name pozostaje bez zmian. Na przykład, jeśli programista naprawia krytyczny błąd w kompilacji hotfix bez zmiany funkcjonalności. Version Name pozostaje 2.0.0, a Version Code zmienia się z 5 na 6. Google Play poprawnie obsłuży taką aktualizację.

// Przykład: version name się nie zmienia, code wzrasta
android {
    defaultConfig {
        versionCode 6  // Było 5 — hotfix bez nowych funkcji
        versionName "2.0.0"  // Nie zmieniło się
    }
}

// Sprawdzanie wersji w runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Kod: $code, Nazwa: $name")

Konfiguracja Version Code w build.gradle

Konfiguracja Version Code odbywa się w pliku build.gradle modułu aplikacji. Pole versionCode przyjmuje liczbę całkowitą i znajduje się w bloku defaultConfig. Dla różnych flavour-kompilacji można ustawić własne wartości przez pole versionCode w konfiguracji produktu.

Podstawowa konfiguracja

// 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 pozwalają używać różnych Version Code dla różnych konfiguracji: wersja demo, osobna wersja dla tabletów. Jeśli w projekcie używane są flavors, końcowy Version Code składa się z liczby bazowej i inkrementu specyficznego dla flavour. Google Play śledzi każdą kombinację niezależnie.

Automatyzacja inkrementu przez CI

W potokach CI/CD (GitHub Actions, GitLab CI, Jenkins) Version Code jest często generowany automatycznie na podstawie numeru kompilacji lub daty. Eliminuje to błędy ludzkie przy ręcznej aktualizacji. Skrypt odczytuje bieżący Version Code z build.gradle, zwiększa go i zapisuje z powrotem przed rozpoczęciem kompilacji.

// Automatyczny inkrement 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
    }
}

Zasady Version Code dla publikacji w Google Play

Google Play ma ścisłe zasady dotyczące Version Code przy publikacji i aktualizacji aplikacji. Naruszenie tych zasad prowadzi do odrzucenia kompilacji lub niemożności wydania aktualizacji. Programista musi rozumieć ograniczenia i strategie zarządzania kodem na wszystkich etapach cyklu życia.

Zasada monotonicznego wzrostu

Google Play nie pozwala przesłać APK lub AAB, którego Version Code jest mniejszy lub równy aktualnie opublikowanemu. Ta zasada działa dla każdej ścieżki (production, beta, alpha) niezależnie. Jeśli w production przesłano kompilację z Version Code 10, a w alpha — z kodem 5, ścieżkę alpha można zaktualizować do 6, 7, 8 lub 9, ale production pozostaje na 10.

Migracja między ścieżkami

Przy promowaniu kompilacji z alpha do beta, a następnie do production Version Code musi wzrastać na każdym etapie. Jeśli wersja alpha ma kod 10, beta może użyć 11, a production — 12. Nie można wdrożyć do production kompilacji z kodem 10, jeśli alpha już używa 10, nawet jeśli production go jeszcze nie widział.

• Monotonous increment — każda kompilacja w ścieżce ma Version Code większy od poprzedniej w tej samej ścieżce
• Cross-track awareness — przy promowaniu między ścieżkami Version Code zwiększa się sekwencyjnie
• Internal testing — ścieżka do testów wewnętrznych używa tych samych zasad monotoniczności
• Multiple APKs — stary format publikacji wymagał unikalnego Version Code dla każdego APK

Błędy przy określaniu Version Code

Najczęstszy błąd — zgodność Version Code w różnych kompilacjach przesłanych do jednej ścieżki. Google Play zwraca błąd APK_VERSION_CODE_ALREADY_EXISTS. Inny błąd — przekroczenie maksymalnej wartości 2100000000, co powoduje błąd kompilacji. Aby uniknąć konfliktów, używaj automatycznego generowania kodu w systemie CI z powiązaniem z numerem kompilacji lub datą kompilacji.

Programiści często popełniają również błąd, nie zwiększając Version Code przy kompilacji hotfix dla alternatywnej ścieżki. Jeśli production ma kod 15, a ścieżka alpha pozostała na 14, przy promowaniu alpha do production Google Play odrzuci kompilację, ponieważ jej kod jest mniejszy niż bieżący production. Śledź monotoniczność kodu we wszystkich ścieżkach jednocześnie — w tym celu wygodnie jest użyć jednego pliku version.properties, z którego wszystkie ścieżki odczytują bieżącą wartość.