<uses-sdk>

Google Play utilise les attributs <uses-sdk> déclarés dans le fichier manifeste de votre application pour filtrer celle-ci et l'exclure des appareils qui ne répondent pas à ses exigences de version de 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 niveau d'API exprimé sous forme d'entier. Le niveau d'API exprimé par une application est comparé à celui d'un système Android donné, qui peut varier d'un appareil Android à l'autre.

Malgré son nom, cet élément permet de 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 obtenir le niveau d'API à partir du numéro de version Android associé. Par exemple, il ne correspond pas à celui de la version majeure ni à la somme de celui de la version majeure et de celui de la version 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. Vous devez toujours déclarer 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 minSdkVersion approprié, l'application plante lors de 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 indique au système que vous avez effectué des tests sur la version cible et que le système ne doit activer aucun comportement de compatibilité pour préserver la compatibilité de votre application avec des versions postérieures de votre application et 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. Cependant, si le niveau d'API de la plate-forme est supérieur à la version déclarée par la targetSdkVersion de votre application, le système peut activer des comportements de compatibilité pour assurer le fonctionnement attendu de votre application. 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, si vous définissez cette valeur sur "11" ou plus, le système applique le thème par défaut Holo à votre application lorsqu'elle s'exécute sur Android 3.0 ou version ultérieure. Le mode de compatibilité de l'écran est également désactivé lorsqu'il s'exécute sur des écrans plus grands, car la prise en charge du niveau d'API 11 est compatible de manière implicite avec 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 conserver 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 minutieusement votre application 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 un cas comme dans l'autre, si l'attribut maxSdkVersion de l'application est inférieur au niveau d'API utilisé par le système lui-même, celui-ci n'autorise 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 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, 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 l'application à nouveau, car le niveau d'API (6) du système est désormais supérieur au niveau d'API maximum pris en charge 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 lancement. 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. Ensuite, dans certains cas, la déclaration de l'attribut peut entraîner la suppression de votre application sur les 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 recevront régulièrement des mises à jour système Over The Air. Vous devez donc prendre en compte leur effet 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 pas et n'appliquent pas l'attribut maxSdkVersion lors de l'installation ou de la nouvelle validation de l'application. Google Play continue toutefois à utiliser l'attribut comme filtre au moment de présenter des applications téléchargeables aux utilisateurs.

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 fournie 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 garantir la robustesse de l'API ainsi que 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 sous forme d'entier, appelé niveau d'API. Chaque version de la plate-forme Android n'est compatible qu'avec un seul niveau d'API, bien que la compatibilité soit implicite pour tous les niveaux d'API antérieurs (jusqu'au niveau d'API 1). La version initiale de la plate-forme Android présentait le niveau d'API 1. Ce numéro a augmenté progressivement avec chaque version ultérieure.

Le tableau suivant spécifie le niveau d'API pris en charge par 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 sur Android

L'identifiant de niveau d'API joue un rôle essentiel 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, 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 sur lesquels elles peuvent s'exécuter, ainsi que le niveau d'API préféré pour lequel elles ont été 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 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.
• android:maxSdkVersion: niveau d'API maximal sur lequel l'application peut s'exécuter. Important:Lisez les informations sur 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 doit inclure dans son fichier manifeste un élément <uses-sdk> avec un attribut android:minSdkVersion. La valeur de android:minSdkVersion est l'entier qui correspond 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 valider à nouveau 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 les compare à ses propres valeurs internes de niveau d'API. Le système autorise le lancement de l'installation uniquement si les conditions suivantes sont remplies:

• Si un attribut android:minSdkVersion est déclaré, sa valeur est inférieure ou égale à l'entier défini pour le niveau d'API du système. Si l'attribut n'est pas déclaré, le système part du principe 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 défini pour le niveau d'API du système. Si l'attribut n'est pas déclaré, le système part du principe que l'application n'a pas de niveau d'API maximal. Pour en savoir plus sur la façon dont le système le gère, consultez la description de cet attribut.

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'il utilise des API introduites dans le niveau d'API spécifié.

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

Considérations concernant le 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 de 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 de manière ascendante 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 par la suite 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 réussir à l'utiliser, 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 d'exécution, mais celle-ci doit toujours disposer de l'API et des fonctionnalités système nécessaires à votre application.

Les modifications à un niveau inférieur à l'API, telles que celles du système sous-jacent, 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 quels seront le comportement et l'apparence de l'application 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 sur 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 lors de leur exécution sur la nouvelle plate-forme et également lors de leur exécution sur des versions ultérieures de la plate-forme, indiquées par le niveau d'API. Toutefois, étant donné que les versions précédentes de la plate-forme n'incluent pas les nouvelles API, les applications qui utilisent celles-ci ne peuvent pas s'exécuter sur ces plates-formes.

Bien qu'il soit peu probable qu'un appareil compatible avec Android soit rétrogradé vers une version antérieure de la plate-forme, il est important de comprendre que de nombreux appareils sur le terrain peuvent exécuter 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 allez compiler l'application. En général, compilez votre application pour 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 la 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. Ainsi, les utilisateurs ne pourront installer votre application que si leurs appareils exécutent une version compatible de la plate-forme Android. Ainsi, votre application peut fonctionner correctement sur leur appareil.

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 les appareils exécutant des versions antérieures de la plate-forme. Dans ce dernier cas, l'application plante lors de l'exécution en tentant d'utiliser des API qui n'existent pas dans les versions précédentes.

Tester l'application pour des niveaux d'API plus élevés

Après avoir compilé votre application, assurez-vous de 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 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 à des fins de test, 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 des niveaux d'API correspondants.

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 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 votre application ne peut y accéder.

Le filtrage par niveau d'API dans la documentation ne permet pas de voir ce qui est nouveau ou introduit dans chaque niveau d'API. Il 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 suivants.

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 tout entière, quel que soit le niveau d'API.

La documentation de référence pour les éléments d'API individuels spécifie le niveau d'API auquel chaque élément est introduit. Le niveau d'API pour les packages et les classes est défini sur "Ajoutée 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.