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 prendre en charge par votre application. Ce niveau d’API est utilisé au moment de l’exécution par Android.

  • Version 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 android SDK, consultez Le programme d’installation du Kit de développement logiciel (SDK) Android.

Notes

À compter d’août 2021, la console Google Play nécessite que les nouvelles applications ciblent le niveau d’API 30 (Android 11.0) ou une version ultérieure. Les applications existantes sont requises pour cibler le niveau d’API 30 ou supérieur à partir de novembre 2021. Pour plus d’informations, consultez la configuration requise au niveau de l’API cible pour la console Play dans « Créer et configurer votre application » dans la documentation de la console Play.

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

Target Framework version defaults to Compile using Android version

Dans la page Manifeste Android , définissez la version Minimale d’Android pour Utiliser la compilation à l’aide de la version du Kit de développement logiciel (SDK) et définissez la version 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 (Dynamics)) :

Minimum and Target Android versions set to Target Framework version

Si vous souhaitez maintenir la compatibilité descendante avec une version antérieure d’Android, définissez la version Minimale d’Android sur la version la plus ancienne d’Android que vous souhaitez que votre application prend 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 14 à l’API niveau 25 :

Compile using API level 25 Nougat, Minimum Android version set to API level 14

Si votre application prend en charge plusieurs versions Android, votre code doit inclure des vérifications d’exécution pour vous assurer que votre application fonctionne avec le paramètre de version Android minimum (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 les niveaux d’API et les bibliothèques 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 d’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 des versions antérieures et les versions 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 passe par plusieurs noms :

  • Version Android, telle qu’Android 9.0
  • Nom de code (ou dessert), tel que Pie
  • Un 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 niveau d’API.

De plus, Xamarin.Android définit les codes de version de build qui correspondent aux niveaux d’API Android actuellement connus. Le tableau suivant peut vous aider à traduire entre le niveau de l’API, la version Android, le nom du 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.4W 20 Juin 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 Oct 2013 BuildVersionCodes.KitKat
Gelée bean 4.3 18 Juillet 2013 BuildVersionCodes.JellyBeanMr2
Gelée bean 4.2-4.2.2 17 Novembre 2012 BuildVersionCodes.JellyBeanMr1
Gelée 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évrier 2011 BuildVersionCodes.HoneyComb
Gingerbread 2.3.3-2.3.4 10 Février 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évrier 2009 BuildVersionCodes.Base11
Base 1.0 1 Oct 2008 BuildVersionCodes.Base

Comme le indique ce tableau, les 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 plus anciennes et plus récentes d’Android. Comment pouvez-vous 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 être unique par version de plateforme Android. Le niveau d’API identifie précisément la version de l’ensemble d’API dans laquelle votre application peut appeler ; il identifie la combinaison d’éléments manifeste, d’autorisations, etc. que vous codez en tant que développeur. Le système 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 de niveau API suivantes :

  • 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 à exécuter votre application.

Ces paramètres permettent de s’assurer que les fonctionnalités nécessaires pour exécuter correctement l’application sont disponibles sur l’appareil Android au moment de l’installation. Si ce n’est pas le cas, l’application n’est pas en cours d’exécution 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 Project

Les sections suivantes expliquent comment utiliser le Gestionnaire du Kit de développement logiciel (SDK) pour préparer votre environnement de développement pour les niveaux d’API que vous souhaitez cibler, suivis d’explications détaillées sur la configuration des paramètres du Framework cible, de la version Minimale d’Android et de la version cible d’Android dans Xamarin.Android.

Plateformes du Kit de développement logiciel (SDK) Android

Avant de pouvoir sélectionner un niveau d’API cible ou minimal dans Xamarin.Android, vous devez installer la version de la plateforme android SDK qui correspond à ce niveau d’API. La plage de choix disponibles pour Target Framework, la version Minimale d’Android et la version Cible d’Android est limitée à la plage 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 du Kit de développement logiciel (SDK) Android requises 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 le programme d’installation du Kit de développement logiciel (SDK) Android.

Framework cible

L’infrastructure cible (également appelée compileSdkVersion) est la version spécifique de l’infrastructure Android (niveau DE l’API) que 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 elle n’a aucun effet sur les API qui sont 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 du runtime.

Le Framework 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 le Framework 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 de Target Framework disponible. Cela vous fournit des messages d’avertissement utiles pour toutes les API déconseillé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 bibliothèque de support : chaque bibliothèque s’attend à ce que votre application soit compilée au niveau de l’API minimale de la bibliothèque ou supérieure.

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 :

Application page of project Properties

Définissez le Framework 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 des appareils correspondant au paramètre Target Framework ou à une version ultérieure ; si le paramètre de version Minimale Android est inférieur au paramètre Target Framework, votre application peut également s’exécuter sur les versions antérieures d’Android. Par exemple, si vous définissez Le Framework cible sur Android 7.1 (Blizzard) et que vous définissez la version Minimale d’Android sur Android 4.0.3 (Ice Cream Sandwich), votre application peut être installée sur n’importe quelle plateforme du niveau d’API 15 au niveau de l’API 25, inclus.

Bien que votre application puisse générer et installer 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 plus récente, votre application obtient une erreur d’exécution et peut-être un incident. 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 elle 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 qui sont suffisamment récents pour les prendre en charge. Les vérifications d’exécution pour les versions Android, plus loin dans ce guide, expliquent comment ajouter ces vérifications d’exécution à votre code.

Pour accéder au paramètre de 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 Minimale Android, vous pouvez sélectionner la version Minimale d’Android pour votre application :

Minimum Android to target option set to Compile using SDK version

Si vous sélectionnez Utiliser Compile à l’aide de la version du KIT DE DÉVELOPPEMENT logiciel (SDK), la version Minimale d’Android sera identique au paramètre Target Framework.

Version d’Android cible

La version d’Android cible (également appelée targetSdkVersion) est le niveau 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 des comportements de compatibilité, ce qui garantit que votre application continue de fonctionner comme vous vous attendez. Android utilise le paramètre de version Target Android de votre application pour déterminer quels changements de comportement peuvent être appliqués à votre application sans le briser (c’est la façon dont Android fournit une compatibilité avancée).

Le Framework cible et la version d’Android cible, tout en ayant des noms très similaires, ne sont pas les mêmes. Le paramètre Target Framework communique les informations au niveau de l’API cible à Xamarin.Android à utiliser au moment de la compilation, tandis que la version d’Android cible communique les informations de niveau API cible à Android à 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 Android cible, vous pouvez sélectionner la version Cible Android de votre application :

Target Android version set to Compile using SDK version

Nous vous recommandons de définir explicitement la version Target Android 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: cela vous permet d’utiliser de nouvelles API avant de travailler sur les modifications de comportement. Pour la plupart des développeurs, nous vous déconseillons de définir la version d’Android cible à utiliser Compile à l’aide de la version du Kit de développement logiciel (SDK).

En général, la version d’Android cible 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 Kit de développement logiciel (SDK), consultez la documentation android developer use-sdk .

Vérifications du runtime pour les versions Android

À mesure que chaque nouvelle version d’Android est publiée, l’API d’infrastructure est mise à jour pour fournir de nouvelles fonctionnalités ou de remplacement. Avec peu d’exceptions, les fonctionnalités d’API des versions antérieures d’Android sont transférées vers des versions Android plus récentes sans modification. Par conséquent, si votre application s’exécute sur un niveau d’API Android particulier, elle peut généralement 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 les versions antérieures d’Android ?

Si vous sélectionnez une version Android minimale 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 de version Android minimum, votre code doit vérifier 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 d’API est inférieur à la version Minimale 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 voulons utiliser la méthode NotificationBuilder.SetCategory pour catégoriser une notification lors de l’exécution sur 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 Android 4.1 Jelly Bean (où SetCategory n’est pas disponible). En faisant 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 où SetCategory il n’est pas disponible, notre code peut détecter le niveau de l’API au moment de l’exécution et appeler SetCategory conditionnellement uniquement lorsque le niveau de l’API est supérieur ou égal au code de version de 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 Minimale Android est définie sur Android 4.1 (niveau d’API 16). Étant donné qu’il SetCategory est disponible au niveau Android.OS.BuildVersionCodes.Lollipop de l’API et versions ultérieures, cet exemple de code appelle SetCategory uniquement lorsqu’il est réellement disponible. Il n’essaie pas d’appeler SetCategory lorsque le niveau de l’API est de 16, 17, 18, 19 ou 20. La fonctionnalité est réduite sur ces versions Android antérieures 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 réduites.

En général, la vérification de la version de build permet à votre code de décider au moment de l’exécution entre faire quelque chose de nouveau et l’ancienne façon. 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 aucune règle rapide et simple qui explique comment réduire ou modifier les fonctionnalités de votre application lorsqu’elle s’exécute sur des versions Android antérieures qui n’ont pas une ou 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 lorsqu’elle Android.OS.Build.VERSION.SdkInt est détectée être inférieure au niveau de l’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 Target Framework : la version Minimale Android et les paramètres de version Android Cible ne sont pas disponibles. C’est parce qu’il n’y a pas de page manifeste Android :

Only the Compile using Android version option is available

Les paramètres de version Android minimale et de version Cible 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 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 de l’API de plateforme sur lequel la bibliothèque sera exécutée. À l’esprit, les bonnes pratiques suivantes doivent être observées lors de la consommation ou de la création de bibliothèques :

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

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

Ces bonnes pratiques sont recommandées pour empêcher la situation où une bibliothèque tente d’appeler une API qui n’est pas disponible au moment de l’exécution (ce qui peut entraîner un blocage de l’application). Si vous êtes développeur de bibliothèque, vous devez vous efforcer de restreindre votre utilisation des appels d’API à un petit sous-ensemble bien établi de la surface totale de l’API. Cela permet de s’assurer que votre bibliothèque peut être utilisée en toute sécurité sur une plus grande gamme de versions Android.

Résumé

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