Partager via

Présentation des niveaux d’API Android

  • Article

Xamarin.Android a plusieurs paramètres au niveau de l’API Android qui déterminent la compatibilité de votre application avec plusieurs versions d’Android. Ce guide explique ce que signifient ces paramètres, comment les configurer et quel effet ils ont sur votre application au moment de l’exécution.

Démarrage rapide

Xamarin.Android expose trois paramètres de projet au niveau de l’API Android :

  • Framework cible : spécifie l’infrastructure à utiliser pour créer votre application. Ce niveau d’API est utilisé au moment de la compilation par Xamarin.Android.

  • Version minimale d’Android : spécifie la version Android la plus ancienne que vous souhaitez que votre application prend en charge. Ce niveau d’API est utilisé au moment de l’exécution par Android.

  • Version d’Android cible : spécifie la version d’Android sur laquelle votre application est destinée à s’exécuter. Ce niveau d’API est utilisé au moment de l’exécution par Android.

Avant de pouvoir configurer un niveau d’API pour votre projet, vous devez installer les composants de la plateforme SDK pour ce niveau d’API. Pour plus d’informations sur le téléchargement et l’installation des composants du Kit de développement logiciel (SDK) Android, consultez Configuration du Kit de développement logiciel (SDK) Android.

Notes

À compter d’août 2021, la console Google Play exige que les nouvelles applications ciblent le niveau d’API 30 (Android 11.0) ou supérieur. Les applications existantes doivent cibler le niveau d’API 30 ou supérieur à compter de novembre 2021. Pour plus d’informations, consultez Exigences au niveau de l’API cible pour la console Play dans « Créer et configurer votre application » dans la documentation play console.

Normalement, les trois niveaux d’API Xamarin.Android sont définis sur la même valeur. Dans la page Application , définissez Compiler à l’aide de la version d’Android (Framework cible) sur la dernière version d’API stable (ou, au minimum, sur la version Android qui dispose de toutes les fonctionnalités dont vous avez besoin). Dans la capture d’écran suivante, l’infrastructure cible est définie sur Android 7.1 (API Level 25 - Nougat) :

La version du framework cible est compilée par défaut à l’aide de la version Android

Dans la page Manifeste Android , définissez la version Minimale d’Android sur Utiliser compiler à l’aide de la version du SDK et définissez la version d’Android cible sur la même valeur que la version du Framework cible (dans la capture d’écran suivante, l’infrastructure Android cible est définie sur Android 7.1 (Nougat)) :

Versions minimale et cible d’Android définies sur La version du Framework cible

Si vous souhaitez maintenir la compatibilité descendante avec une version antérieure d’Android, définissez La version minimale d’Android sur la cible sur la version la plus ancienne d’Android que votre application doit prendre en charge. (Notez que le niveau d’API 14 est le niveau d’API minimal requis pour les services Google Play et la prise en charge de Firebase.) L’exemple de configuration suivant prend en charge les versions Android du niveau d’API 14 au niveau d’API 25 :

Compiler à l’aide de l’API niveau 25 Nougat, version Android minimale définie sur le niveau d’API 14

Si votre application prend en charge plusieurs versions d’Android, votre code doit inclure des vérifications d’exécution pour vous assurer que votre application fonctionne avec le paramètre Version minimale d’Android (voir Vérifications d’exécution pour les versions Android ci-dessous pour plus d’informations). Si vous consommez ou créez une bibliothèque, consultez Niveaux et bibliothèques d’API ci-dessous pour connaître les meilleures pratiques en matière de configuration des paramètres au niveau de l’API pour les bibliothèques.

Versions Android et niveaux d’API

À mesure que la plateforme Android évolue et que de nouvelles versions Android sont publiées, chaque version d’Android se voit attribuer un identificateur entier unique, appelé niveau d’API. Par conséquent, chaque version d’Android correspond à un seul niveau d’API Android. Étant donné que les utilisateurs installent des applications sur les versions antérieures et les plus récentes d’Android, les applications Android réelles doivent être conçues pour fonctionner avec plusieurs niveaux d’API Android.

Versions d’Android

Chaque version d’Android est accompagnée de plusieurs noms :

  • La version Android, telle qu’Android 9.0
  • Nom de code (ou dessert), tel que Pie
  • Niveau d’API correspondant, tel que le niveau d’API 28

Un nom de code Android peut correspondre à plusieurs versions et niveaux d’API (comme indiqué dans le tableau ci-dessous), mais chaque version Android correspond exactement à un seul niveau d’API.

En outre, Xamarin.Android définit des codes de version de build qui correspondent aux niveaux actuellement connus de l’API Android. Le tableau suivant peut vous aider à traduire entre le niveau de l’API, la version Android, le nom de code et le code de version de build Xamarin.Android (les codes de version de build sont définis dans l’espace Android.OS de noms) :

Nom Version Niveau d’API Final Build Version Code
Q 10.0 29 Août 2020 BuildVersionCodes.Q
Pie 9.0 28 Août 2018 BuildVersionCodes.P
Oreo 8.1 27 Déc. 2017 BuildVersionCodes.OMr1
Oreo 8.0 26 Août 2017 BuildVersionCodes.O
Nougat 7.1 25 Déc 2016 BuildVersionCodes.NMr1
Nougat 7.0 24 Août 2016 BuildVersionCodes.N
Marshmallow 6.0 23 Aug 2015 BuildVersionCodes.M
Lollipop 5.1 22 Mar 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 Nov 2014 BuildVersionCodes.Lollipop
Kitkat Watch 4,4 W 20 Juin 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 Oct 2013 BuildVersionCodes.KitKat
Jelly Bean 4.3 18 Juil 2013 BuildVersionCodes.JellyBeanMr2
Jelly Bean 4.2-4.2.2 17 Nov 2012 BuildVersionCodes.JellyBeanMr1
Jelly Bean 4.1-4.1.1 16 Juin 2012 BuildVersionCodes.JellyBean
Sandwich à la crème glacée 4.0.3-4.0.4 15 Déc 2011 BuildVersionCodes.IceCreamSandwichMr1
Sandwich à la crème glacée 4.0-4.0.2 14 Octobre 2011 BuildVersionCodes.IceCreamSandwich
Honeycomb 3.2 13 Juin 2011 BuildVersionCodes.HoneyCombMr2
Honeycomb 3.1.x 12 Mai 2011 BuildVersionCodes.HoneyCombMr1
Honeycomb 3.0.x 11 Fév 2011 BuildVersionCodes.HoneyComb
Gingerbread 2.3.3-2.3.4 10 Fév 2011 BuildVersionCodes.GingerBreadMr1
Gingerbread 2.3-2.3.2 9 Novembre 2010 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 Juin 2010 BuildVersionCodes.Froyo
Eclair 2.1.x 7 Jan. 2010 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 Déc 2009 BuildVersionCodes.Eclair01
Eclair 2.0 5 Novembre 2009 BuildVersionCodes.Eclair
Graphique en anneau 1.6 4 Sep 2009 BuildVersionCodes.Donut
Cupcake 1.5 3 Mai 2009 BuildVersionCodes.Cupcake
Base 1.1 2 Fév 2009 BuildVersionCodes.Base11
Base 1,0 1 Oct 2008 BuildVersionCodes.Base

Comme l’indique ce tableau, de nouvelles versions d’Android sont publiées fréquemment, parfois plus d’une version par an. Par conséquent, l’univers des appareils Android qui peuvent exécuter votre application inclut une grande variété de versions Android plus anciennes et plus récentes. Comment garantir que votre application s’exécutera de manière cohérente et fiable sur autant de versions différentes d’Android ? Les niveaux d’API d’Android peuvent vous aider à gérer ce problème.

Niveaux d’API Android

Chaque appareil Android s’exécute exactement à un niveau d’API : ce niveau d’API est garanti comme étant unique par version de la plateforme Android. Le niveau d’API identifie précisément la version du jeu d’API que votre application peut appeler ; il identifie la combinaison d’éléments de manifeste, d’autorisations, etc. que vous codez en tant que développeur. Le système de niveaux d’API Android permet à Android de déterminer si une application est compatible avec une image système Android avant d’installer l’application sur un appareil.

Lorsqu’une application est générée, elle contient les informations suivantes au niveau de l’API :

  • Niveau d’API cible d’Android sur lequel l’application est créée pour s’exécuter.

  • Niveau minimal de l’API Android qu’un appareil Android doit avoir pour exécuter votre application.

Ces paramètres permettent de s’assurer que les fonctionnalités nécessaires à l’exécution correcte de l’application sont disponibles sur l’appareil Android au moment de l’installation. Si ce n’est pas le cas, l’exécution de l’application est bloquée sur cet appareil. Par exemple, si le niveau d’API d’un appareil Android est inférieur au niveau d’API minimal que vous spécifiez pour votre application, l’appareil Android empêche l’utilisateur d’installer votre application.

Paramètres au niveau de l’API du projet

Les sections suivantes expliquent comment utiliser le Gestionnaire sdk pour préparer votre environnement de développement pour les niveaux d’API que vous souhaitez cibler, puis des explications détaillées sur la configuration de l’infrastructure cible, de la version minimale d’Android et des paramètres de version Android cible dans Xamarin.Android.

Plateformes du SDK Android

Avant de pouvoir sélectionner un niveau cible ou minimum de l’API dans Xamarin.Android, vous devez installer la version de plateforme du SDK Android qui correspond à ce niveau d’API. La gamme de choix disponibles pour l’infrastructure cible, la version minimale d’Android et la version Cible d’Android est limitée à la gamme de versions du KIT de développement logiciel (SDK) Android que vous avez installées. Vous pouvez utiliser le Gestionnaire du Kit de développement logiciel (SDK) pour vérifier que les versions requises du SDK Android sont installées, et vous pouvez l’utiliser pour ajouter les nouveaux niveaux d’API dont vous avez besoin pour votre application. Si vous n’êtes pas familiarisé avec l’installation des niveaux d’API, consultez Configuration du SDK Android.

Framework cible

L’infrastructure cible (également appelée compileSdkVersion) est la version spécifique de l’infrastructure Android (niveau DE l’API) pour laquelle votre application est compilée au moment de la génération. Ce paramètre spécifie les API que votre application s’attend à utiliser lorsqu’elle s’exécute, mais il n’a aucun effet sur les API réellement disponibles pour votre application lorsqu’elle est installée. Par conséquent, la modification du paramètre Framework cible ne modifie pas le comportement d’exécution.

L’infrastructure cible identifie les versions de bibliothèque auxquelles votre application est liée. Ce paramètre détermine les API que vous pouvez utiliser dans votre application. Par exemple, si vous souhaitez utiliser la méthode NotificationBuilder.SetCategory introduite dans Android 5.0 Lollipop, vous devez définir l’infrastructure cible sur le niveau d’API 21 (Lollipop) ou version ultérieure. Si vous définissez l’infrastructure cible de votre projet sur un niveau d’API tel que le niveau d’API 19 (KitKat) et que vous essayez d’appeler la SetCategory méthode dans votre code, vous obtiendrez une erreur de compilation.

Nous vous recommandons de toujours compiler avec la dernière version disponible de Target Framework. Cela vous fournit des messages d’avertissement utiles pour toutes les API dépréciées qui peuvent être appelées par votre code. L’utilisation de la dernière version de Target Framework est particulièrement importante lorsque vous utilisez les dernières versions de la bibliothèque de support : chaque bibliothèque s’attend à ce que votre application soit compilée au niveau d’API minimal ou supérieur de cette bibliothèque.

Pour accéder au paramètre Target Framework dans Visual Studio, ouvrez les propriétés du projet dans Explorateur de solutions et sélectionnez la page Application :

Page d’application des propriétés du projet

Définissez l’infrastructure cible en sélectionnant un niveau d’API dans le menu déroulant sous Compiler à l’aide de la version Android , comme indiqué ci-dessus.

Version minimale d’Android

La version Minimale d’Android (également appelée minSdkVersion) est la version la plus ancienne du système d’exploitation Android (c’est-à-dire le niveau d’API le plus bas) qui peut installer et exécuter votre application. Par défaut, une application ne peut être installée que sur les appareils correspondant au paramètre Framework cible ou supérieur ; si le paramètre Version minimale d’Android est inférieur au paramètre Framework cible, votre application peut également s’exécuter sur des versions antérieures d’Android. Par exemple, si vous définissez l’infrastructure cible sur Android 7.1 (Nougat) et que vous définissez la version Minimale d’Android sur Android 4.0.3 (Sandwich glace), votre application peut être installée sur n’importe quelle plateforme, du niveau API 15 au niveau d’API 25 inclus.

Bien que votre application puisse générer et installer avec succès sur cette plage de plateformes, cela ne garantit pas qu’elle s’exécutera correctement sur toutes ces plateformes. Par exemple, si votre application est installée sur Android 5.0 (Lollipop) et que votre code appelle une API disponible uniquement dans Android 7.1 (Nougat) et versions ultérieures, votre application obtiendra une erreur d’exécution et peut-être se bloquer. Par conséquent, votre code doit s’assurer, au moment de l’exécution, qu’il appelle uniquement les API prises en charge par l’appareil Android sur lequel il s’exécute. En d’autres termes, votre code doit inclure des vérifications d’exécution explicites pour vous assurer que votre application utilise des API plus récentes uniquement sur les appareils suffisamment récents pour les prendre en charge. Runtime Checks for Android Versions, plus loin dans ce guide, explique comment ajouter ces vérifications d’exécution à votre code.

Pour accéder au paramètre Version minimale d’Android dans Visual Studio, ouvrez les propriétés du projet dans Explorateur de solutions et sélectionnez la page Manifeste Android. Dans le menu déroulant sous Version Android minimale , vous pouvez sélectionner la version Android minimale pour votre application :

Option Minimale d’Android à cible définie sur Compiler à l’aide de la version du KIT de développement logiciel (SDK)

Si vous sélectionnez Utiliser compiler à l’aide de la version du KIT de développement logiciel (SDK), la version minimale d’Android sera identique au paramètre Framework cible.

Version d’Android cible

La version d’Android cible (également appelée targetSdkVersion) est le niveau d’API de l’appareil Android où l’application s’attend à s’exécuter. Android utilise ce paramètre pour déterminer s’il faut activer les comportements de compatibilité, ce qui garantit que votre application continue de fonctionner comme prévu. Android utilise le paramètre De version Android cible de votre application pour déterminer les modifications de comportement qui peuvent être appliquées à votre application sans la briser (c’est ainsi qu’Android fournit la compatibilité avant).

Le Framework cible et la version d’Android cible, bien qu’ayant des noms très similaires, ne sont pas la même chose. Le paramètre Target Framework communique des informations au niveau de l’API cible à Xamarin.Android pour une utilisation au moment de la compilation, tandis que la version d’Android cible communique les informations de niveau de l’API cible à Android pour les utiliser au moment de l’exécution (lorsque l’application est installée et s’exécute sur un appareil).

Pour accéder à ce paramètre dans Visual Studio, ouvrez les propriétés du projet dans Explorateur de solutions et sélectionnez la page Manifeste Android. Dans le menu déroulant sous Version d’Android cible , vous pouvez sélectionner la version d’Android cible pour votre application :

Version d’Android cible définie sur Compiler à l’aide de la version du Kit de développement logiciel (SDK)

Nous vous recommandons de définir explicitement la version d’Android cible sur la dernière version d’Android que vous utilisez pour tester votre application. Dans l’idéal, il doit être défini sur la dernière version du Kit de développement logiciel (SDK) Android, ce qui vous permet d’utiliser de nouvelles API avant d’effectuer les modifications de comportement. Pour la plupart des développeurs, nous déconseillons de définir la version d’Android cible sur Utiliser Compiler à l’aide de la version du SDK.

En général, la version cible d’Android doit être limitée par la version minimale d’Android et l’infrastructure cible. Plus précisément :

Version <Android minimale = Version <Android cible = Framework cible

Pour plus d’informations sur les niveaux du SDK, consultez la documentation android developer uses-sdk .

Vérifications du runtime pour les versions Android

À mesure que chaque nouvelle version d’Android est publiée, l’API framework est mise à jour pour fournir des fonctionnalités nouvelles ou de remplacement. À quelques exceptions près, les fonctionnalités d’API des versions Android antérieures sont transférées dans des versions Android plus récentes sans modification. Par conséquent, si votre application s’exécute à un niveau d’API Android particulier, elle sera généralement en mesure de s’exécuter sur un niveau d’API Android ultérieur sans modification. Mais que se passe-t-il si vous souhaitez également exécuter votre application sur des versions antérieures d’Android ?

Si vous sélectionnez une version Minimale d’Android inférieure à votre paramètre Target Framework, certaines API peuvent ne pas être disponibles pour votre application au moment de l’exécution. Toutefois, votre application peut toujours s’exécuter sur un appareil antérieur, mais avec des fonctionnalités réduites. Pour chaque API qui n’est pas disponible sur les plateformes Android correspondant à votre paramètre Version minimale d’Android, votre code doit case activée explicitement la valeur de la Android.OS.Build.VERSION.SdkInt propriété pour déterminer le niveau d’API de la plateforme sur laquelle l’application s’exécute. Si le niveau de l’API est inférieur à la version Minimale d’Android qui prend en charge l’API que vous souhaitez appeler, votre code doit trouver un moyen de fonctionner correctement sans effectuer cet appel d’API.

Par exemple, supposons que nous souhaitions utiliser la méthode NotificationBuilder.SetCategory pour catégoriser une notification lors de l’exécution d’Android 5.0 Lollipop (et versions ultérieures), mais nous voulons toujours que notre application s’exécute sur des versions antérieures d’Android telles que Jelly Bean Android 4.1 (où SetCategory n’est pas disponible). En référence à la table de versions Android au début de ce guide, nous voyons que le code de version de build pour Android 5.0 Lollipop est Android.OS.BuildVersionCodes.Lollipop. Pour prendre en charge les versions antérieures d’Android lorsque SetCategory n’est pas disponible, notre code peut détecter le niveau de l’API au moment de l’exécution et appeler SetCategory de manière conditionnelle uniquement lorsque le niveau de l’API est supérieur ou égal au code de version de la build Lollipop :

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

Dans cet exemple, l’infrastructure cible de notre application est définie sur Android 5.0 (niveau d’API 21) et sa version Android minimale est définie sur Android 4.1 (niveau API 16). Étant SetCategory disponible au niveau Android.OS.BuildVersionCodes.Lollipop de l’API et versions ultérieures, cet exemple de code n’appellera SetCategory que lorsqu’il est réellement disponible : il ne tentera pas d’appeler SetCategory lorsque le niveau d’API est 16, 17, 18, 19 ou 20. La fonctionnalité est réduite sur ces versions antérieures d’Android uniquement dans la mesure où les notifications ne sont pas triées correctement (car elles ne sont pas classées par type), mais les notifications sont toujours publiées pour alerter l’utilisateur. Notre application fonctionne toujours, mais ses fonctionnalités sont légèrement diminuées.

En général, la version de build case activée aide votre code à décider au moment de l’exécution entre la nouvelle méthode et l’ancienne méthode. Par exemple :

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Il n’existe pas de règle simple et rapide qui explique comment réduire ou modifier les fonctionnalités de votre application lorsqu’elle s’exécute sur d’anciennes versions d’Android qui ne disposent pas d’une ou de plusieurs API. Dans certains cas (comme dans l’exemple SetCategory ci-dessus), il suffit d’omettre l’appel d’API lorsqu’il n’est pas disponible. Toutefois, dans d’autres cas, vous devrez peut-être implémenter d’autres fonctionnalités pour Android.OS.Build.VERSION.SdkInt quand est détecté comme étant inférieur au niveau d’API dont votre application a besoin pour présenter son expérience optimale.

Niveaux et bibliothèques d’API

Lorsque vous créez un projet de bibliothèque Xamarin.Android (par exemple, une bibliothèque de classes ou une bibliothèque de liaisons), vous pouvez configurer uniquement le paramètre Framework cible : la version minimale d’Android et les paramètres de version Android cible ne sont pas disponibles. Cela est dû au fait qu’il n’existe pas de page de manifeste Android :

Seule l’option Compiler à l’aide de la version Android est disponible

Les paramètres Version minimale d’Android et Version cible d’Android ne sont pas disponibles, car la bibliothèque résultante n’est pas une application autonome : la bibliothèque peut être exécutée sur n’importe quelle version d’Android, en fonction de l’application avec laquelle elle est empaquetée. Vous pouvez spécifier la façon dont la bibliothèque doit être compilée, mais vous ne pouvez pas prédire le niveau d’API de plateforme sur lequel la bibliothèque sera exécutée. Dans cette optique, les meilleures pratiques suivantes doivent être observées lors de la consommation ou de la création de bibliothèques :

  • Lors de la consommation d’une bibliothèque Android : si vous consommez une bibliothèque Android dans votre application, veillez à définir le paramètre Framework cible de votre application sur un niveau d’API au moins aussi élevé que le paramètre Framework cible de la bibliothèque.

  • Lors de la création d’une bibliothèque Android : si vous créez une bibliothèque Android pour une utilisation par d’autres applications, veillez à définir son paramètre Target Framework sur le niveau d’API minimal dont il a besoin pour la compilation.

Ces meilleures pratiques sont recommandées pour éviter qu’une bibliothèque tente d’appeler une API qui n’est pas disponible au moment de l’exécution (ce qui peut provoquer le blocage de l’application). Si vous êtes développeur de bibliothèques, vous devez vous efforcer de limiter votre utilisation des appels d’API à un sous-ensemble restreint et bien établi de la surface totale de l’API. Cela permet de garantir que votre bibliothèque peut être utilisée en toute sécurité dans un plus large éventail de versions d’Android.

Résumé

Ce guide explique comment les niveaux d’API Android sont utilisés pour gérer la compatibilité des applications entre les différentes versions d’Android. Il fournissait des étapes détaillées pour configurer les paramètres du projet Xamarin.Android Target Framework, Version minimale d’Android et Version cible d’Android . Il fournissait des instructions sur l’utilisation du Gestionnaire du KIT de développement logiciel (SDK) Android pour installer des packages sdk, incluait des exemples d’écriture de code pour traiter les différents niveaux d’API au moment de l’exécution et expliquait comment gérer les niveaux d’API lors de la création ou de la consommation de bibliothèques Android. Il a également fourni une liste complète qui relie les niveaux d’API aux numéros de version Android (tels que Android 4.4), aux noms de version Android (tels que Kitkat) et aux codes de version de build Xamarin.Android.