<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 :

Vous permet d'exprimer la compatibilité d'une application avec une ou plusieurs versions de la plate-forme Android à l'aide d'un nombre entier de niveau d'API. 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 entier. Vous ne pouvez pas déduire le niveau d'API à partir du numéro de version Android qui lui est associé. Par exemple, il ne s'agit pas de la version majeure, ni de 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 que l'application s'exécute. 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, 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 non disponibles. 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 et qu'il n'active aucun comportement de compatibilité pour maintenir la compatibilité ascendante de votre application avec la version cible. L'application peut toujours s'exécuter dans des versions antérieures (à 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 targetSdkVersion de votre application, le système peut activer des 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 une valeur supérieure permet au système d'appliquer le thème Holo par défaut à votre application lorsqu'elle s'exécute sous Android 3.0 ou version ultérieure. De plus, le mode de compatibilité de l'écran est désactivé sur les grands écrans, car la prise en charge du niveau d'API 11 prend implicitement en charge les grands écrans.

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 niveau d'API le plus récent, puis testez votre application de manière approfondie sur la version de plate-forme correspondante.

Introduit au niveau d'API 4

android:maxSdkVersion

Entier désignant le niveau d'API maximal sur lequel l'application est conçue pour s'exécuter.

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 exécute 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 du système Over The Air 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, un certain 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 à nouveau l'application, car le niveau d'API (6) du système est désormais supérieur au niveau maximal accepté 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 à mesure qu'elles sont publiées. Par définition, les nouvelles versions de la plate-forme sont entièrement compatibles avec les versions antérieures. Votre application fonctionne correctement avec les nouvelles versions, à condition qu'elle n'utilise que des API standards et qu'elle respecte les bonnes pratiques de développement. Ensuite, dans certains cas, 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 des mises à jour système périodiques Over The Air. Vous devez donc prendre en compte leurs effets sur votre application avant de définir cet attribut.

Introduit au 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 revalidation. Google Play continue toutefois d'utiliser l'attribut comme filtre lors de la présentation aux utilisateurs d'applications téléchargeables.

Première apparition :

Niveau d'API 1

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

Le niveau d'API est une valeur entière 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 sont obsolètes, mais ne sont pas supprimées, afin que les applications existantes puissent toujours les utiliser.

Dans de très rares cas, certaines 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 assurer 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 antérieurs (jusqu'au niveau d'API 1). La version initiale de la plate-forme Android fournissait le niveau d'API 1, et les versions suivantes l'ont augmenté.

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

Utilisations du niveau d'API sous 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 accepte.
• Il permet aux applications de décrire la révision de l'API de framework dont elles ont besoin.
• Il permet au système de négocier l'installation d'applications sur l'appareil de l'utilisateur afin 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 manifeste fourni par l'API du framework (<uses-sdk>) pour décrire les niveaux d'API minimal et maximal avec lesquels elles peuvent s'exécuter, ainsi que le niveau d'API préféré pour lequel elles sont conçues. 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é à ceux définis pour le niveau d'API minimal.
• android:maxSdkVersion: niveau d'API maximal sur lequel l'application peut s'exécuter. Important:Consultez les informations sur cet attribut sur cette page avant de l'utiliser.

Par exemple, pour spécifier le niveau d'API système minimal dont une application a besoin pour s'exécuter, elle 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 de la revalider 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 et compare les valeurs à son propre niveau d'API interne. Le système ne permet le lancement de 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. S'il n'est pas déclaré, le système suppose que l'application n'a pas de niveau d'API maximal. Lisez la description de cet attribut pour savoir comment le système le traite.

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 avec un niveau d'API 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 empêchant l'application de s'installer si le niveau d'API le plus bas requis est supérieur à celui de la version de la plate-forme sur l'appareil cible.

Considérations liées au développement

Les sections suivantes fournissent des informations sur le niveau d'API à prendre en compte lors du développement de votre application.

Compatibilité ascendante des applications

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

Étant donné que presque toutes les modifications apportées à l'API de framework sont additives, 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 avec 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ù l'application 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 par la suite 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 d'exécution de l'environnement, qui dispose toujours des fonctionnalités d'API et du système dont votre application dépend.

Les modifications apportées 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 sont exécutées sur la nouvelle plate-forme et également sur des versions ultérieures de la plate-forme, comme spécifié par le niveau d'API. Toutefois, comme les versions antérieures de la plate-forme n'incluent pas les nouvelles API, les applications qui les utilisent ne peuvent pas s'exécuter sur ces plates-formes.

Il est peu probable qu'un appareil Android soit rétrogradé vers une version précédente de la plate-forme, mais il est important de comprendre 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 par rapport à laquelle vous compilez l'application. En général, compilez votre application sur 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. Après avoir 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 la dernière version de la plate-forme. Ainsi, les utilisateurs ne peuvent installer votre application que si leurs appareils exécutent une version compatible de la plate-forme Android. Cela permet également de garantir que votre application peut fonctionner correctement 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 qui exécutent 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.

Effectuer des tests par rapport à des niveaux d'API plus élevés

Une fois votre application compilée, 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 qui utilisent un niveau d'API supérieur à celui utilisé par 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 l'utiliser pour n'afficher la documentation que pour les parties de l'API 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 grisées et leur contenu est masqué, car elles ne sont pas accessibles à votre application.

Le filtrage par niveau d'API dans la documentation ne fournit pas une vue de ce qui est nouveau ou introduit dans 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 consultation complète de la documentation, sélectionnez REL en haut du menu de niveau d'API. Par défaut, le filtrage au niveau de l'API est désactivé pour que vous puissiez afficher l'API de framework complète, quel que soit le niveau d'API.

La documentation de référence sur les é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 pour les membres du cours est spécifié dans leurs en-têtes de description détaillée, dans la marge de droite.