Version Code: co to je, číselný identifikátor a aktualizace

Co je Version Code v Androidu

Version Code — je celé číslo typu Integer, které je přiřazeno každému sestavení aplikace Android. Na rozdíl od Version Name se Version Code uživateli nezobrazuje a je používán výhradně operačním systémem a Google Play k porovnávání verzí při instalaci aktualizací.

Formát Version Code

Version Code musí být kladné celé číslo v rozsahu od 1 do 2100000000. Každé následující sestavení musí mít Version Code přísně větší než předchozí. Pokud vývojář vydal sestavení s Version Code 5, další publikace může použít 6, 7 nebo libovolné číslo větší než 5, ale ne 4 a ne znovu 5.

Historie vzniku

Google zavedl rozdělení na Version Code a Version Name s vydáním Android SDK v roce 2007. Version Code byl navržen jako strojový identifikátor pro automatické porovnávání verzí, zatímco Version Name — jako čtitelný štítek pro člověka. Toto rozdělení umožňuje vývojáři pojmenovat verzi libovolně, přičemž zachovává přísné pořadí aktualizací prostřednictvím číselného kódu.

Jak funguje verzování prostřednictvím Version Code

Mechanismus porovnávání Version Code je zabudován do operačního systému Android a obchodu Google Play. Při každé publikaci Google Play kontroluje, zda je Version Code nového sestavení větší než kód nainstalované verze. Pokud podmínka není splněna, publikace je zamítnuta s chybou.

Proces kontroly aktualizace

Když zařízení kontaktuje Google Play pro kontrolu aktualizací, server porovná Version Code nainstalované aplikace s maximálním dostupným v obchodě. Pokud je kód na serveru větší — spustí se stahování a instalace aktualizace. Uživatel vidí Version Name zadaný vývojářem, ale rozhodnutí o aktualizaci se provádí na základě Version Code.

Inkrement Version Code

Vývojáři používají různé strategie inkrementace Version Code. Nejjednodušší je zvýšení o 1 při každém sestavení. Pro CI/CD potrubí se často používá timestamp nebo číslo sestavení: 2026070301 (rok-měsíc-den-číslo). Je důležité, aby kód monotónně rostl a neopakoval se mezi různými sestaveními a tracky Google Play.

• Monotónní inkrement — zvýšení o 1 při každém commitu do release větve
• Formát timestamp — 20260703 pro denní sestavení, 2026070301 pro několik denně
• SemVer v číslech — 100010000 pro verzi 1.1.0 (major 1, minor 1, patch 0)
• Číslo sestavení — použití BUILD_NUMBER z CI systému (Jenkins, GitHub Actions)

Rozdíly mezi Version Code a Version Name

Version Code a Version Name — dvě nezávislá pole v build.gradle, která plní různé funkce. Version Code je interní identifikátor pro systém, Version Name je marketingový štítek pro uživatele. Mohou se měnit nezávisle na sobě.

Version Name pro uživatele

Version Name — je řetězec, který se zobrazuje v nastavení aplikace, v Google Play a v dialogových oknech aktualizace. Vývojář může zadat libovolný formát: 1.0.0, 2.3.1-beta, 3.0-rc1. Pro porovnávání textových verzí se Version Name nepoužívá — Google Play se vždy spoléhá na Version Code.

Scénáře odchylek

Je možná situace, kdy Version Code roste, ale Version Name zůstává stejné. Například, pokud vývojář opravuje kritickou chybu v hotfix sestavení bez změny funkcionality. Version Name zůstává 2.0.0 a Version Code se mění z 5 na 6. Google Play takovou aktualizaci správně zpracuje.

// Příklad: version name se nemění, code se zvyšuje
android {
    defaultConfig {
        versionCode 6  // Bylo 5 — hotfix bez nových funkcí
        versionName "2.0.0"  // Nezměnilo se
    }
}

// Kontrola verzí v runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Kód: $code, Název: $name")

Nastavení Version Code v build.gradle

Nastavení Version Code se provádí v souboru build.gradle modulu aplikace. Pole versionCode přijímá celé číslo a nachází se v bloku defaultConfig. Pro různá flavour sestavení lze nastavit vlastní hodnoty pomocí pole versionCode v konfiguraci produktu.

Základní konfigurace

// 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 umožňují používat různé Version Code pro různé konfigurace: demo verze, samostatná verze pro tablety. Pokud jsou v projektu použity flavors, výsledný Version Code se skládá základního čísla a inkrementu specifického pro flavour. Google Play sleduje každou kombinaci nezávisle.

Automatizace inkrementu pomocí CI

V CI/CD potrubích (GitHub Actions, GitLab CI, Jenkins) je Version Code často generován automaticky na základě čísla sestavení nebo data. Tím se eliminují lidské chyby při ruční aktualizaci. Skript načte aktuální Version Code z build.gradle, zvýší jej a zapíše zpět před zahájením sestavení.

// Automatický 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
    }
}

Pravidla Version Code pro publikaci v Google Play

Google Play má přísná pravidla pro Version Code při publikování a aktualizaci aplikací. Porušení těchto pravidel vede k zamítnutí sestavení nebo nemožnosti vydat aktualizaci. Vývojář musí rozumět omezením a strategiím správy kódu ve všech fázích životního cyklu.

Pravidlo monotónního růstu

Google Play neumožňuje nahrát APK nebo AAB, jehož Version Code je menší nebo roven aktuálně publikovanému. Toto pravidlo platí pro každý track (production, beta, alpha) nezávisle. Pokud byl do production nahrán build s Version Code 10 a do alpha s kódem 5, alpha track lze aktualizovat na 6, 7, 8 nebo 9, ale production zůstává na 10.

Migrace mezi tracky

Při propagaci sestavení z alpha do beta a poté do production musí Version Code v každé fázi růst. Pokud má alpha verze kód 10, beta může použít 11 a production 12. Nelze nasadit do production sestavení s kódem 10, pokud alpha již používá 10, i když jej production ještě neviděl.

• Monotonous increment — každé sestavení v tracku má Version Code větší než předchozí ve stejném tracku
• Cross-track awareness — při propagaci mezi tracky se Version Code sekvenčně zvyšuje
• Internal testing — track pro interní testování používá stejná pravidla monotónnosti
• Multiple APKs — starý formát publikace vyžadoval jedinečný Version Code pro každý APK

Chyby při zadávání Version Code

Nejčastější chyba — shoda Version Code v různých sestaveních nahraných do jednoho tracku. Google Play vrátí chybu APK_VERSION_CODE_ALREADY_EXISTS. Další chyba — překročení maximální hodnoty 2100000000, což způsobí chybu při kompilaci. Abyste předešli konfliktům, používejte automatické generování kódu v CI systému s vazbou na číslo sestavení nebo datum sestavení.

Vývojáři často dělají také chybu, kdy nezvýší Version Code při hotfix sestavení pro alternativní track. Pokud má production kód 15 a alpha track zůstal na 14, při propagaci alpha do production Google Play zamítne sestavení, protože jeho kód je menší než aktuální production. Sledujte monotónnost kódu ve všech trackech současně — k tomu je vhodné použít jeden soubor version.properties, ze kterého všechny tracky čtou aktuální hodnotu.