Gérer les versions de votre application

La gestion des versions est un composant essentiel de votre stratégie de mise à niveau et de maintenance des applications. La gestion des versions est importante pour les raisons suivantes :

  • Les utilisateurs doivent disposer d'informations spécifiques sur la version de l'application installée sur leurs appareils et sur les versions de mise à niveau disponibles pour l'installation.
  • D'autres applications, y compris celles que vous publiez en tant que suite, doivent interroger le système pour connaître la version de votre application, afin de déterminer la compatibilité et d'identifier les dépendances.
  • Les services via lesquels vous publiez vos applications peuvent également avoir besoin d'interroger votre application pour connaître sa version, afin qu'ils puissent la présenter aux utilisateurs. Un service de publication peut aussi avoir besoin de vérifier la version de l'application pour déterminer la compatibilité et établir des relations de mise à niveau/rétrogradation.

Le système Android utilise les informations sur la version de votre application pour empêcher un utilisateur de revenir à une version antérieure. Il ne se sert pas de ces informations pour appliquer des restrictions sur les mises à niveau ou la compatibilité des applications tierces. Votre application doit appliquer toutes les restrictions de version et en informer les utilisateurs.

Le système Android applique la compatibilité des versions du système, comme indiqué par le paramètre minSdk dans les fichiers de compilation. Ce paramètre permet à une application de spécifier l'API système minimale avec laquelle elle est compatible. Pour en savoir plus sur les exigences d'API, consultez Spécifier les exigences du niveau d'API.

Les exigences liées à la gestion des versions varient selon les projets. Cependant, de nombreux développeurs considèrent la gestion sémantique des versions comme une bonne stratégie de base.

Définir les informations de version de l'application

Pour définir les informations de version de votre application, définissez les valeurs des paramètres de version dans les fichiers de compilation Gradle :

Groovy

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...

Kotlin

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...

Paramètres de la version

Définissez les valeurs des deux paramètres de version disponibles : versionCode et versionName.

versionCode
Entier positif utilisé comme numéro de version interne. Ce numéro permet de déterminer si une version est plus récente qu'une autre. Plus un chiffre est élevé, plus la version est récente. Il ne s'agit pas du numéro de version présenté aux utilisateurs. Ce numéro est défini par le paramètre versionName. Le système Android utilise la valeur versionCode pour se protéger contre les rétrogradations en empêchant les utilisateurs d'installer un APK dont la version de versionCode est antérieure à la version actuellement installée sur leur appareil.

La valeur est un entier positif afin que d'autres applications puissent l'évaluer de manière programmatique, par exemple pour vérifier une relation de mise à niveau ou de rétrogradation. Vous pouvez définir cette valeur sur n'importe quel entier positif de votre choix, mais vous devez vous assurer que chaque version successive de votre application utilise une valeur supérieure.

Remarque : La valeur maximale autorisée par Google Play pour versionCode est 2100000000.

Vous ne pouvez pas importer d'APK sur le Play Store avec un versionCode que vous avez déjà utilisé pour une version précédente.

Remarque : Dans certains cas, vous souhaiterez peut-être importer une version de votre application dont le versionCode est inférieur à celui de la version la plus récente. Par exemple, si vous publiez plusieurs APK, vous avez peut-être prédéfini des plages versionCode pour des APK spécifiques. Pour déterminer comment attribuer des valeurs versionCode à plusieurs APK, consultez Attribuer des codes de version.

En règle générale, vous publiez la première version de votre application avec versionCode défini sur "1", puis augmentez la valeur de façon monotone à chaque version, qu'il s'agisse d'une version majeure ou mineure. Autrement dit, la valeur versionCode ne ressemble pas nécessairement à la version de l'application que l'utilisateur voit. Les applications et les services de publication ne doivent pas présenter cette valeur de version aux utilisateurs.

versionName

Chaîne utilisée comme numéro de version présenté aux utilisateurs. Ce paramètre peut être spécifié en tant que chaîne brute ou en tant que référence à une ressource de chaîne.

Cette valeur est une chaîne qui vous permet de décrire la version de l'application sous la forme d'une chaîne <major>.<minor>.<point> ou de tout autre type d'identifiant de version absolu ou relatif. versionName est la seule valeur que les utilisateurs peuvent voir.

Définir les valeurs de la version

Vous pouvez définir des valeurs par défaut pour ces paramètres en les incluant dans le bloc defaultConfig {}, imbriqué dans le bloc android {} du fichier build.gradle ou build.gradle.kts de votre module. Vous pouvez ensuite ignorer ces valeurs par défaut pour différentes versions de votre application en définissant des valeurs distinctes pour chaque type de compilation ou type de produit. Le fichier suivant affiche les paramètres versionCode et versionName dans le bloc defaultConfig {}, ainsi que le bloc productFlavors {}.

Ces valeurs sont ensuite fusionnées dans le fichier manifeste de votre application au cours du processus de compilation.

Groovy

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }

Kotlin

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }

Dans le bloc defaultConfig {} de cet exemple, la valeur versionCode indique que l'APK actuel contient la deuxième version de l'application, et la chaîne versionName spécifie qu'elle sera présentée aux utilisateurs en tant que version 1.1. Ce fichier définit également deux types de produit, "demo" et "full". Étant donné que le type de produit "demo" définit versionName comme "1.1-demo", le build "demo" utilise ce versionName au lieu de la valeur par défaut. Le bloc de type de produit "full" ne définit pas versionName. Il utilise donc la valeur par défaut "1.1".

Remarque : Si votre application définit la version de l'application directement dans l'élément <manifest>, les valeurs de version du fichier de compilation Gradle ignorent les paramètres du fichier manifeste. En outre, la définition de ces paramètres dans les fichiers de compilation Gradle vous permet de spécifier différentes valeurs pour différentes versions de votre application. Pour plus de flexibilité et pour éviter tout risque d'écrasement lors de la fusion du fichier manifeste, supprimez ces attributs de l'élément <manifest> et définissez vos paramètres de version dans les fichiers de compilation Gradle à la place.

Le framework Android fournit une API qui vous permet d'interroger le système pour obtenir les informations de version de votre application. Pour obtenir des informations sur la version, utilisez la méthode PackageManager.getPackageInfo(java.lang.String, int).

Spécifier les exigences du niveau d'API

Si votre application nécessite une version minimale spécifique de la plate-forme Android, vous pouvez spécifier cette exigence de version en tant que paramètres de niveau d'API dans le fichier build.gradle ou build.gradle.kts de l'application. Au cours du processus de compilation, ces paramètres sont fusionnés dans le fichier manifeste de votre application. La spécification des exigences de niveau d'API garantit que votre application ne peut être installée que sur les appareils exécutant une version compatible de la plate-forme Android.

Remarque : Si vous spécifiez des exigences de niveau d'API directement dans le fichier manifeste de votre application, les paramètres correspondants dans les fichiers de compilation remplacent les paramètres du fichier manifeste. En outre, la définition de ces paramètres dans les fichiers de compilation Gradle vous permet de spécifier différentes valeurs pour différentes versions de votre application. Pour plus de flexibilité et pour éviter tout risque d'écrasement lors de la fusion du fichier manifeste, supprimez ces attributs de l'élément <uses-sdk> et définissez vos paramètres de niveau d'API dans les fichiers de compilation Gradle à la place.

Deux paramètres de niveau d'API sont disponibles :

  • minSdk : version minimale de la plate-forme Android sur laquelle l'application sera exécutée, spécifiée par l'identifiant de niveau d'API de la plate-forme.
  • targetSdk : spécifie le niveau d'API pour lequel l'application a été conçue. Dans certains cas, cela permet à l'application d'utiliser des éléments de fichier manifeste ou des comportements définis dans le niveau d'API cible, au lieu d'être limitée à ceux définis pour le niveau d'API minimal.

Pour spécifier des exigences de niveau d'API par défaut dans un fichier build.gradle ou build.gradle.kts, ajoutez un ou plusieurs des paramètres de niveau d'API au bloc defaultConfig{}, imbriqués dans le bloc android {}. Vous pouvez également ignorer ces valeurs par défaut pour différentes versions de votre application en ajoutant les paramètres aux types de compilation ou aux types de produit.

Le fichier suivant spécifie les paramètres minSdk et targetSdk par défaut dans le bloc defaultConfig {}, et ignore minSdk pour un type de produit :

Groovy

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

Lors de la préparation de l'installation de votre application, le système vérifie la valeur de ces paramètres et les compare à la version du système. Si la valeur minSdk est supérieure à la version du système, le système empêche l'installation de l'application.

Si vous ne spécifiez pas ces paramètres, le système suppose que votre application est compatible avec toutes les versions de plate-forme. Cela revient à définir minSdk sur 1

Pour en savoir plus, consultez Qu'est-ce que le niveau d'API ?. Pour en savoir plus sur les paramètres de compilation Gradle, consultez Configurer des variantes de compilation.