<uses-sdk>

Google Play utilise les attributs <uses-sdk> déclarés dans le fichier manifeste de votre application pour la filtrer dans les appareils qui ne répondent pas aux exigences de version de la plate-forme. Avant de définir ces attributs, assurez-vous de bien comprendre les filtres Google Play.

syntaxe :
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
Contenu dans :
<manifest>
Description :

Permet d'exprimer la compatibilité d'une application avec une ou plusieurs versions de la plate-forme Android à l'aide d'un niveau d'API entier. Le niveau d'API exprimé par une application est comparé au niveau d'API d'un système Android donné, qui peut varier selon les appareils Android.

Malgré son nom, cet élément est utilisé pour spécifier le niveau d'API, et non le numéro de version du kit de développement logiciel (SDK) ou de la plate-forme Android. Le niveau d'API est toujours un seul entier. Vous ne pouvez pas déduire le niveau d'API à partir du numéro de version Android associé. Par exemple, ce n'est pas identique à la version majeure ou à la somme des versions majeure et mineure.

Lisez également le document sur la gestion des versions de vos applications.

Attributs :
android:minSdkVersion
Entier désignant le niveau d'API minimal requis pour l'exécution de l'application. Le système Android empêche l'utilisateur d'installer l'application si le niveau d'API du système est inférieur à la valeur spécifiée dans cet attribut. Déclarez toujours cet attribut.

Attention:Si vous ne déclarez pas cet attribut, le système suppose la valeur par défaut "1 ", ce qui indique que votre application est compatible avec toutes les versions d'Android. Si ce n'est pas le cas et que vous n'avez pas déclaré le bon minSdkVersion, alors lorsqu'elle est installée sur un système avec un niveau d'API incompatible, l'application plante pendant l'exécution lorsqu'elle tente d'accéder aux API indisponibles. Pour cette raison, veillez à déclarer le niveau d'API approprié dans l'attribut minSdkVersion.

android:targetSdkVersion
Entier désignant le niveau d'API ciblé par l'application. Si ce champ n'est pas défini, la valeur par défaut est égale à celle fournie pour minSdkVersion.

Cet attribut informe le système que vous avez effectué des tests par rapport à la version cible. Le système n'active aucun comportement de compatibilité permettant de maintenir la compatibilité ascendante de votre application avec la version cible. L'application peut toujours s'exécuter sur les versions antérieures (jusqu'à minSdkVersion).

Comme Android évolue à chaque nouvelle version, certains comportements et même certaines apparences peuvent changer. Toutefois, si le niveau d'API de la plate-forme est supérieur à la version déclarée par le fichier targetSdkVersion de votre application, le système peut activer les comportements de compatibilité afin que votre application continue de fonctionner comme prévu. Vous pouvez désactiver ces comportements de compatibilité en spécifiant la targetSdkVersion en fonction du niveau d'API de la plate-forme sur laquelle elle est en cours d'exécution.

Par exemple, définir cette valeur sur "11" ou plus permet au système d'appliquer le thème par défaut Holo à votre application lorsqu'elle s'exécute sur Android 3.0 ou version ultérieure et désactive également le mode de compatibilité de l'écran sur les grands écrans, car la prise en charge du niveau d'API 11 prend implicitement en charge les écrans plus grands.

Le système peut activer de nombreux comportements de compatibilité en fonction de la valeur que vous définissez pour cet attribut. Plusieurs de ces comportements sont décrits par les versions de plate-forme correspondantes dans la documentation de référence Build.VERSION_CODES.

Pour gérer votre application avec chaque version d'Android, augmentez la valeur de cet attribut pour qu'elle corresponde au dernier niveau d'API, puis testez minutieusement votre application sur la version de plate-forme correspondante.

Date d'introduction: niveau d'API 4

android:maxSdkVersion
Entier désignant le niveau d'API maximal pour lequel l'application est conçue.

Sous Android 1.5, 1.6, 2.0 et 2.0.1, le système vérifie la valeur de cet attribut lors de l'installation d'une application et lors de la nouvelle validation de l'application après une mise à jour du système. Dans les deux cas, si l'attribut maxSdkVersion de l'application est inférieur au niveau d'API utilisé par le système lui-même, le système ne permet pas l'installation de l'application. En cas de nouvelle validation après une mise à jour du système, votre application est supprimée de l'appareil.

Pour illustrer l'impact de cet attribut sur votre application après une mise à jour du système, prenons l'exemple suivant :

Une application qui déclare maxSdkVersion="5" dans son fichier manifeste est publiée sur Google Play. Un utilisateur dont l'appareil est équipé d'Android 1.6 (niveau d'API 4) télécharge et installe l'application. Après quelques semaines, l'utilisateur reçoit une mise à jour Over The Air du système vers Android 2.0 (niveau d'API 5). Une fois la mise à jour installée, le système vérifie l'attribut maxSdkVersion de l'application et valide cette dernière à nouveau.

L'application fonctionne normalement. Cependant, quelque temps plus tard, l'appareil reçoit une autre mise à jour du système, cette fois vers Android 2.0.1 (niveau d'API 6). Après la mise à jour, le système ne peut plus valider l'application à nouveau, car le niveau d'API (6) du système est désormais supérieur à la valeur maximale acceptée par l'application (5). Le système empêche l'affichage de l'application pour l'utilisateur en la supprimant de l'appareil.

Avertissement:Nous vous déconseillons de déclarer cet attribut. Tout d'abord, il n'est pas nécessaire de définir l'attribut pour bloquer le déploiement de votre application sur les nouvelles versions de la plate-forme Android dès leur publication. Par définition, les nouvelles versions de la plate-forme sont entièrement compatibles avec les versions antérieures. Votre application fonctionne correctement sur les nouvelles versions, à condition qu'elle n'utilise que des API standards et qu'elle respecte les bonnes pratiques de développement. Deuxièmement, la déclaration de l'attribut peut entraîner la suppression de votre application des appareils des utilisateurs après une mise à jour du système vers un niveau d'API supérieur. La plupart des appareils sur lesquels votre application est susceptible d'être installée reçoivent régulièrement des mises à jour système Over The Air. Avant de définir cet attribut, tenez compte de leur effet sur votre application.

Date d'introduction: niveau d'API 4

Certaines versions d'Android (au-delà d'Android 2.0.1) ne vérifient ni n'appliquent l'attribut maxSdkVersion lors de l'installation ou de la nouvelle validation. Toutefois, Google Play continue d'utiliser l'attribut comme filtre lorsqu'il présente aux utilisateurs des applications disponibles au téléchargement.
Première apparition :
Niveau d'API 1

Qu'est-ce que le niveau d'API ?

Le niveau d'API est un nombre entier qui identifie de manière unique la révision de l'API de framework proposée par une version de la plate-forme Android.

La plate-forme Android fournit une API de framework que les applications peuvent utiliser pour interagir avec le système Android sous-jacent. L'API de framework se compose des éléments suivants :

  • Un ensemble principal de packages et de classes
  • Un ensemble d'éléments et d'attributs XML pour la déclaration d'un fichier manifeste
  • Un ensemble d'éléments et d'attributs XML permettant de déclarer des ressources et d'y accéder
  • Un ensemble d'intents
  • Un ensemble d'autorisations que les applications peuvent demander, ainsi que les applications d'autorisations incluses dans le système

Chaque version successive de la plate-forme Android peut inclure des mises à jour de l'API de framework d'application Android fournie.

Les mises à jour de l'API de framework sont conçues pour que la nouvelle API reste compatible avec les versions antérieures. Autrement dit, la plupart des modifications de l'API s'ajoutent les unes aux autres et introduisent de nouvelles fonctionnalités ou des fonctionnalités de remplacement. À mesure que certaines parties de l'API sont mises à niveau, les anciennes parties remplacées deviennent obsolètes, mais ne sont pas supprimées, afin que les applications existantes puissent toujours les utiliser.

Dans de très rares cas, des parties de l'API sont modifiées ou supprimées, bien que ces modifications ne soient généralement nécessaires que pour assurer la robustesse de l'API et la sécurité des applications ou du système. Toutes les autres parties d'API issues des révisions précédentes sont transférées sans modification.

L'API de framework fournie par une plate-forme Android est spécifiée à l'aide d'un identifiant entier appelé niveau d'API. Chaque version de la plate-forme Android n'accepte qu'un seul niveau d'API, bien que la prise en charge soit implicite pour tous les niveaux d'API précédents (jusqu'au niveau d'API 1). La version initiale de la plate-forme Android proposait le niveau d'API 1, et les versions suivantes ont incrémenté le niveau d'API.

Le tableau suivant spécifie le niveau d'API compatible avec chaque version de la plate-forme Android. Pour connaître le nombre relatif d'appareils exécutant chaque version, consultez le tableau de bord de distribution.

Version de la plate-formeNiveau d'APIVERSION_CODENotes
Android 15 API 34 → DP2 VANILLA_ICE_CREAM Points forts de la plate-forme
Android 14 34 UPSIDE_DOWN_CAKE Points forts de la plate-forme
Android 13 33 TIRAMISU Points forts de la plate-forme
Android 12 32 S_V2 Points forts de la plate-forme
31 S Points forts de la plate-forme
Android 11 30 R Points forts de la plate-forme
Android 10 29 Q Points forts de la plate-forme
Android 9 28 P Points forts de la plate-forme
Android 8.1 27 O_MR1 Points forts de la plate-forme
Android 8.0 26 O Points forts de la plate-forme
Android 7.1.1
Android 7.1
25 N_MR1 Points forts de la plate-forme
Android 7.0 24 N Points forts de la plate-forme
Android 6.0 23 M Points forts de la plate-forme
Android 5.1 22 LOLLIPOP_MR1 Points forts de la plate-forme
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat pour accessoires connectés uniquement
Android 4.4 19 KITKAT Points forts de la plate-forme
Android 4.3 18 JELLY_BEAN_MR2 Points forts de la plate-forme
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 Points forts de la plate-forme
Android 4.1, 4.1.1 16 JELLY_BEAN Points forts de la plate-forme
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Points forts de la plate-forme
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 Points forts de la plate-forme
Android 3.0.x 11 HONEYCOMB Points forts de la plate-forme
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Points forts de la plate-forme
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Points forts de la plate-forme
Android 2.1.x 7 ECLAIR_MR1 Points forts de la plate-forme
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Points forts de la plate-forme
Android 1.5 3 CUPCAKE Points forts de la plate-forme
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Utilisations du niveau d'API sur Android

L'identifiant de niveau d'API joue un rôle clé pour garantir la meilleure expérience possible aux utilisateurs et aux développeurs d'applications:

  • Il permet à la plate-forme Android de décrire la révision maximale de l'API de framework qu'elle prend en charge.
  • Il permet aux applications de décrire la révision de l'API de framework dont elles ont besoin.
  • Elle permet au système de négocier l'installation d'applications sur l'appareil de l'utilisateur, de sorte que les applications incompatibles avec les versions ne soient pas installées.

Chaque version de la plate-forme Android stocke son identifiant de niveau d'API en interne, dans le système Android lui-même.

Les applications peuvent utiliser un élément de fichier manifeste fourni par l'API de framework (<uses-sdk>) pour décrire les niveaux d'API minimal et maximal sous lesquels elles peuvent s'exécuter, ainsi que le niveau d'API préféré qu'elles sont conçues pour prendre en charge. L'élément comporte trois attributs clés :

  • android:minSdkVersion: niveau d'API minimal sur lequel l'application peut s'exécuter. La valeur par défaut est "1".
  • android:targetSdkVersion: niveau d'API pour lequel l'application est conçue pour s'exécuter. Dans certains cas, cela permet à l'application d'utiliser des éléments du 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.
  • android:maxSdkVersion: niveau d'API maximal sur lequel l'application peut s'exécuter. Important:Lisez les informations concernant cet attribut sur cette page avant de l'utiliser.

Par exemple, pour spécifier le niveau d'API système minimal requis pour qu'une application s'exécute, l'application inclut dans son fichier manifeste un élément <uses-sdk> avec un attribut android:minSdkVersion. La valeur de android:minSdkVersion est l'entier correspondant au niveau d'API de la première version de la plate-forme Android sous laquelle l'application peut s'exécuter.

Lorsque l'utilisateur tente d'installer une application ou lorsqu'il revalide une application après une mise à jour du système, le système Android vérifie d'abord les attributs <uses-sdk> dans le fichier manifeste de l'application, puis compare les valeurs à son propre niveau d'API interne. Le système ne permet de lancer l'installation que si les conditions suivantes sont remplies:

  • Si un attribut android:minSdkVersion est déclaré, sa valeur est inférieure ou égale à l'entier du niveau d'API du système. S'il n'est pas déclaré, le système suppose que l'application nécessite le niveau d'API 1.
  • Si un attribut android:maxSdkVersion est déclaré, sa valeur est supérieure ou égale à l'entier du niveau d'API du système. Si cette valeur n'est pas déclarée, le système suppose que l'application n'a pas de niveau d'API maximal. Lisez la description de cet attribut pour découvrir comment le système le gère.

Lorsqu'il est déclaré dans le fichier manifeste d'une application, un élément <uses-sdk> peut se présenter comme suit :

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

La principale raison pour laquelle une application déclare un niveau d'API dans android:minSdkVersion est d'indiquer au système Android qu'elle utilise des API introduites au niveau d'API spécifié.

Si l'application s'installe d'une manière ou d'une autre sur une plate-forme dont le niveau d'API est inférieur, elle plante au moment de l'exécution lorsqu'elle tente d'accéder à des API qui n'existent pas. Le système empêche ce résultat en ne laissant pas l'application s'installer si le niveau d'API le plus bas dont elle a besoin est supérieur à celui de la version de la plate-forme sur l'appareil cible.

Considérations relatives au développement

Les sections suivantes fournissent des informations sur le niveau d'API dont vous devez tenir compte lorsque vous développez votre application.

Compatibilité ascendante des applications

Les applications Android sont généralement compatibles avec les nouvelles versions de la plate-forme Android.

Comme presque toutes les modifications apportées à l'API de framework sont cumulatives, une application Android développée à l'aide d'une version donnée de l'API, comme spécifié par son niveau d'API, est compatible avec les versions ultérieures de la plate-forme Android et les niveaux d'API supérieurs. L'application peut s'exécuter sur toutes les versions ultérieures de la plate-forme Android, sauf dans les cas isolés où elle utilise une partie de l'API qui est ensuite supprimée pour une raison quelconque.

La compatibilité ascendante est importante, car de nombreux appareils Android reçoivent des mises à jour système OTA (Over The Air). L'utilisateur peut installer votre application et l'utiliser correctement, puis recevoir ultérieurement une mise à jour OTA vers une nouvelle version de la plate-forme Android. Une fois la mise à jour installée, votre application s'exécute dans une nouvelle version de l'environnement, mais qui dispose toujours de l'API et des fonctionnalités système dont dépend votre application.

Les modifications sous l'API, telles que celles du système sous-jacent lui-même, peuvent affecter votre application lorsqu'elle est exécutée dans le nouvel environnement. En tant que développeur d'applications, il est important que vous compreniez comment l'application se présente et se comporte dans chaque environnement système.

Pour vous aider à tester votre application sur différentes versions de la plate-forme Android, le SDK Android inclut plusieurs plates-formes téléchargeables. Chaque plate-forme inclut une image système compatible que vous pouvez exécuter dans un AVD pour tester votre application.

Rétrocompatibilité des applications

Les applications Android ne sont pas nécessairement rétrocompatibles avec les versions de la plate-forme Android antérieures à la version avec laquelle elles ont été compilées.

Chaque nouvelle version de la plate-forme Android peut inclure de nouvelles API de framework, telles que celles permettant aux applications d'accéder aux nouvelles fonctionnalités de la plate-forme ou celles qui remplacent des parties d'API existantes. Les nouvelles API sont accessibles aux applications lorsqu'elles s'exécutent sur la nouvelle plate-forme, mais aussi sur des versions ultérieures de la plate-forme, comme spécifié par le niveau d'API. Toutefois, comme les versions précédentes de la plate-forme n'incluent pas les nouvelles API, les applications qui utilisent les nouvelles API ne peuvent pas s'exécuter sur ces plates-formes.

Bien qu'il ne soit pas probable qu'un appareil Android soit rétrogradé vers une version précédente de la plate-forme, il est important de noter qu'il est probable que de nombreux appareils sur le terrain exécutent des versions antérieures de la plate-forme. Même parmi les appareils qui reçoivent les mises à jour OTA, certains peuvent être à la traîne et ne pas recevoir de mise à jour pendant un certain temps.

Sélectionner une version de la plate-forme et un niveau d'API

Lorsque vous développez votre application, vous choisissez la version de la plate-forme sur laquelle vous compilez l'application. En règle générale, compilez votre application avec la version la plus basse possible de la plate-forme compatible avec votre application.

Vous pouvez déterminer la version de plate-forme la plus basse possible en compilant l'application sur des cibles de compilation successives de plus en plus basses. Une fois que vous avez déterminé la version la plus basse, créez un AVD à l'aide de la version de plate-forme et du niveau d'API correspondants, puis testez entièrement votre application. Veillez à déclarer un attribut android:minSdkVersion dans le fichier manifeste de l'application et à définir sa valeur sur le niveau d'API de la version de la plate-forme.

Déclarer un niveau d'API minimal

Si vous créez une application qui utilise des API ou des fonctionnalités système introduites dans la dernière version de la plate-forme, définissez l'attribut android:minSdkVersion sur le niveau d'API de cette dernière version. Ainsi, les utilisateurs ne peuvent installer votre application que si leurs appareils exécutent une version compatible de la plate-forme Android. Cela permet de garantir le bon fonctionnement de votre application sur leurs appareils.

Si votre application utilise des API introduites dans la dernière version de la plate-forme, mais ne déclare pas d'attribut android:minSdkVersion, elle s'exécute correctement sur les appareils exécutant la dernière version de la plate-forme, mais pas sur ceux exécutant des versions antérieures. Dans ce dernier cas, l'application plante au moment de l'exécution lorsqu'elle tente d'utiliser des API qui n'existent pas dans les versions antérieures.

Tester avec des niveaux d'API plus élevés

Après avoir compilé votre application, veillez à la tester sur la plate-forme spécifiée dans l'attribut android:minSdkVersion de l'application. Pour ce faire, créez un AVD ayant la version de plate-forme requise par votre application. En outre, pour vérifier la compatibilité ascendante, exécutez et testez l'application sur toutes les plates-formes dont le niveau d'API est supérieur à celui de votre application.

Le SDK Android inclut plusieurs versions de plate-forme que vous pouvez utiliser, y compris la dernière version, et fournit un outil de mise à jour qui vous permet de télécharger d'autres versions de la plate-forme, si nécessaire.

Pour accéder au programme de mise à jour, utilisez l'outil de ligne de commande android, situé dans le répertoire <sdk>/tools. Vous pouvez lancer l'outil de mise à jour du SDK en exécutant android sdk. Vous pouvez également double-cliquer sur le fichier android.bat (Windows) ou android (OS X/Linux).

Pour exécuter votre application sur différentes versions de plate-forme dans l'émulateur, créez un AVD pour chaque version de plate-forme que vous souhaitez tester. Pour en savoir plus sur les AVD, consultez Créer et gérer des appareils virtuels. Si vous utilisez un appareil physique pour les tests, assurez-vous de connaître le niveau d'API de la plate-forme Android qu'il exécute. Consultez le tableau de ce document pour obtenir la liste des versions de la plate-forme et de leurs niveaux d'API.

Filtrer la documentation de référence par niveau d'API

Les pages de documentation de référence de la plate-forme Android proposent une commande "Niveau d'API" en haut à gauche de chaque page. Vous pouvez utiliser la commande pour n'afficher la documentation que pour les parties de l'API qui sont réellement accessibles à votre application, en fonction du niveau d'API spécifié dans l'attribut android:minSdkVersion de son fichier manifeste.

Pour utiliser le filtrage, sélectionnez le niveau d'API spécifié par votre application dans le menu. Les API introduites dans un niveau d'API ultérieur sont alors grisées et leur contenu est masqué, car elles ne sont pas accessibles par votre application.

Le filtrage par niveau d'API dans la documentation ne fournit pas de vue des nouveautés ou des ajouts à chaque niveau d'API. Elle permet d'afficher l'intégralité de l'API associée à un niveau d'API donné, tout en excluant les éléments d'API introduits dans les niveaux d'API ultérieurs.

Pour revenir à la documentation complète, sélectionnez REL en haut du menu du niveau d'API. Par défaut, le filtrage au niveau de l'API est désactivé. Vous pouvez donc afficher l'API de framework dans son intégralité, quel que soit le niveau d'API.

La documentation de référence des éléments d'API individuels spécifie le niveau d'API auquel chaque élément est introduit. Le niveau d'API des packages et des classes est spécifié comme "Ajouté au niveau d'API" en haut à droite de la zone de contenu de chaque page de documentation. Le niveau d'API des membres du cours est spécifié dans leurs en-têtes de description détaillés, dans la marge de droite.