Version Code : ce que c'est, identifiant numérique et mises à jour

Qu'est-ce que le Version Code sous Android

Version Code est un nombre entier de type Integer attribué à chaque compilation d'une application Android. Contrairement au Version Name, le Version Code n'est pas affiché à l'utilisateur et est utilisé exclusivement par le système d'exploitation et Google Play pour comparer les versions lors de l'installation des mises à jour.

Format du Version Code

Version Code doit être un nombre entier positif compris entre 1 et 2100000000. Chaque compilation ultérieure doit avoir un Version Code strictement supérieur à la précédente. Si un développeur a publié une compilation avec le Version Code 5, la publication suivante peut utiliser 6, 7 ou tout nombre supérieur à 5, mais pas 4 ni à nouveau 5.

Historique de l'origine

Google a introduit la séparation entre Version Code et Version Name avec le lancement du SDK Android en 2007. Le Version Code a été conçu comme un identifiant machine pour la comparaison automatique des versions, tandis que le Version Name a été créé comme une étiquette lisible par l'homme. Cette séparation permet au développeur de nommer la version comme il le souhaite tout en maintenant un ordre strict des mises à jour via le code numérique.

Comment fonctionne le versionnement via le Version Code

Le mécanisme de comparaison du Version Code est intégré au système d'exploitation Android et au Google Play Store. À chaque publication, Google Play vérifie que le Version Code de la nouvelle compilation est supérieur au code de la version installée. Si la condition n'est pas remplie, la publication est rejetée avec une erreur.

Processus de vérification des mises à jour

Lorsqu'un appareil contacte Google Play pour vérifier les mises à jour, le serveur compare le Version Code de l'application installée avec le maximum disponible dans le store. Si le code sur le serveur est supérieur, le téléchargement et l'installation de la mise à jour démarrent. L'utilisateur voit le Version Name spécifié par le développeur, mais la décision de mise à jour est prise sur la base du Version Code.

IncRémentation du Version Code

Les développeurs appliquent différentes stratégies pour incrémenter le Version Code. La plus simple est d'augmenter de 1 à chaque compilation. Pour les pipelines CI/CD, on utilise souvent un timestamp ou le numéro de compilation : 2026070301 (année-mois-jour-numéro). Il est important que le code augmente de manière monotone et ne se répète pas entre différentes compilations et pistes Google Play.

• IncRémentation monotone — augmentation de 1 à chaque commit dans la branche de release
• Format timestamp — 20260703 pour les compilations quotidiennes, 2026070301 pour plusieurs par jour
• SemVer en nombres — 100010000 pour la version 1.1.0 (major 1, minor 1, patch 0)
• Numéro de compilation — utilisation du BUILD_NUMBER du système CI (Jenkins, GitHub Actions)

Différences entre le Version Code et le Version Name

Version Code et Version Name sont deux champs indépendants dans build.gradle qui remplissent des fonctions différentes. Le Version Code est un identifiant interne pour le système, le Version Name est une étiquette marketing pour l'utilisateur. Ils peuvent changer indépendamment l'un de l'autre.

Version Name pour l'utilisateur

Version Name est une chaîne qui s'affiche dans les paramètres de l'application, dans Google Play et dans les dialogues de mise à jour. Le développeur peut spécifier n'importe quel format : 1.0.0, 2.3.1-beta, 3.0-rc1. Le Version Name n'est pas utilisé pour comparer les versions textuelles — Google Play se base toujours sur le Version Code.

Scénarios de divergence

Une situation est possible où le Version Code augmente tandis que le Version Name reste le même. Par exemple, si un développeur corrige un bogue critique dans une compilation hotfix sans modifier les fonctionnalités. Le Version Name reste 2.0.0, tandis que le Version Code passe de 5 à 6. Google Play traitera correctement cette mise à jour.

// Exemple : le version name ne change pas, le code augmente
android {
    defaultConfig {
        versionCode 6  // Était 5 — hotfix sans nouvelles fonctionnalités
        versionName "2.0.0"  // N'a pas changé
    }
}

// Vérification des versions à l'exécution
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code : $code, Name : $name")

Configuration du Version Code dans build.gradle

La configuration du Version Code se fait dans le fichier build.gradle du module de l'application. Le champ versionCode accepte un nombre entier et fait partie du bloc defaultConfig. Pour différentes compilations de flavors, des valeurs personnalisées peuvent être définies via le champ versionCode dans la configuration du produit.

Configuration de base

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

Les Product flavors permettent d'utiliser différents Version Codes pour différentes configurations : version démo, version séparée pour tablettes. Si des flavors sont utilisés dans le projet, le Version Code final est composé du nombre de base et de l'incrément spécifique au flavor. Google Play suit chaque combinaison indépendamment.

Automatisation de l'incrément via CI

Dans les pipelines CI/CD (GitHub Actions, GitLab CI, Jenkins), le Version Code est souvent généré automatiquement en fonction du numéro de compilation ou de la date. Cela élimine l'erreur humaine lors des mises à jour manuelles. Le script lit le Version Code actuel depuis build.gradle, l'incrémente et le réécrit avant de démarrer la compilation.

// Incrémentation automatique du 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
    }
}

Particularités du Version Code pour la publication sur Google Play

Google Play a des règles strictes pour le Version Code lors de la publication et de la mise à jour des applications. La violation de ces règles entraîne le rejet de la compilation ou l'impossibilité de publier une mise à jour. Le développeur doit comprendre les limitations et les stratégies de gestion du code à toutes les étapes du cycle de vie.

Règle d'incrémentation monotone

Google Play ne permet pas de télécharger un APK ou AAB dont le Version Code est inférieur ou égal à celui actuellement publié. Cette règle s'applique à chaque piste (production, beta, alpha) indépendamment. Si une compilation avec le Version Code 10 a été téléchargée en production et une avec le code 5 en alpha, la piste alpha peut être mise à jour vers 6, 7, 8 ou 9, mais la production reste à 10.

Migration entre les pistes

Lors de la promotion d'une compilation de alpha vers beta puis vers production, le Version Code doit augmenter à chaque étape. Si la version alpha a le code 10, beta peut utiliser 11 et production 12. Vous ne pouvez pas déployer en production une compilation avec le code 10 si alpha utilise déjà 10, même si production ne l'a pas encore vu.

• IncRémentation monotone — chaque compilation dans une piste a un Version Code supérieur à la précédente dans la même piste
• Conscience inter-pistes — lors de la promotion entre pistes, le Version Code augmente séquentiellement
• Tests internes — la piste de test interne utilise les mêmes règles de monotonie
• APK multiples — l'ancien format de publication exigeait un Version Code unique pour chaque APK

Erreurs lors de la spécification du Version Code

L'erreur la plus courante est la correspondance du Version Code dans différentes compilations téléchargées sur la même piste. Google Play renvoie l'erreur APK_VERSION_CODE_ALREADY_EXISTS. Une autre erreur est le dépassement de la valeur maximale de 2100000000, ce qui entraîne un échec de compilation. Pour éviter les conflits, utilisez la génération automatique de code dans votre système CI liée au numéro de compilation ou à la date de compilation.

Les développeurs commettent également souvent l'erreur de ne pas incrémenter le Version Code lors de la compilation d'une hotfix pour une piste alternative. Si la production a le code 15 et que la piste alpha est restée à 14, lors de la promotion de alpha vers production, Google Play rejettera la compilation car son code est inférieur au code actuel de production. Surveillez la monotonie du code sur toutes les pistes simultanément — pour cela, il est pratique d'utiliser un seul fichier version.properties à partir duquel toutes les pistes lisent la valeur actuelle.