Descripción de los niveles de API de Android

  • Artículo

Xamarin.Android tiene varias opciones de configuración de nivel de API de Android que determinan la compatibilidad de la aplicación con varias versiones de Android. En esta guía se explica qué significan estas opciones, cómo configurarlas y qué efecto tienen en la aplicación en tiempo de ejecución.

Inicio rápido

Xamarin.Android expone tres valores de proyecto de nivel de API de Android:

  • Plataforma de destino: especifica qué marco se va a usar para compilar la aplicación. Xamarin.Android usa este nivel de API en tiempo de compilación .

  • Versión mínima de Android : especifica la versión de Android más antigua que quiere que admita la aplicación. Android usa este nivel de API en tiempo de ejecución .

  • Versión de Android de destino: especifica la versión de Android en la que se va a ejecutar la aplicación. Android usa este nivel de API en tiempo de ejecución .

Para poder configurar un nivel de API para el proyecto, debe instalar los componentes de la plataforma del SDK para ese nivel de API. Para obtener más información sobre cómo descargar e instalar componentes de Android SDK, consulte Configuración de Android SDK.

Nota

A partir de agosto de 2021, Google Play Console requiere que las nuevas aplicaciones tienen como destino el nivel de API 30 (Android 11.0) o superior. Las aplicaciones existentes deben tener como destino el nivel de API 30 o superior a partir de noviembre de 2021. Para obtener más información, consulte Requisitos de nivel de API de destino para Play Console en "Crear y configurar la aplicación" en la documentación de Play Console.

Normalmente, los tres niveles de API de Xamarin.Android se establecen en el mismo valor. En la página Aplicación , establezca Compilar con la versión de Android (Plataforma de destino) en la versión de API estable más reciente (o, como mínimo, en la versión de Android que tenga todas las características que necesita). En la captura de pantalla siguiente, la plataforma de destino se establece en Android 7.1 (nivel de API 25 - Nougat):

La versión de la plataforma de destino tiene como valor predeterminado Compilar con la versión de Android

En la página Manifiesto de Android , establezca la versión mínima de Android en Usar compilación con la versión del SDK y establezca la versión de Android de destino en el mismo valor que la versión de La plataforma de destino (en la captura de pantalla siguiente, la plataforma android de destino se establece en Android 7.1 (Nougat)):

Versiones mínimas y de Android de destino establecidas en Versión de la plataforma de destino

Si desea mantener la compatibilidad con versiones anteriores con una versión anterior de Android, establezca Versión mínima de Android como destino a la versión más antigua de Android que desea que admita la aplicación. (Tenga en cuenta que el nivel de API 14 es el nivel de API mínimo necesario para los servicios de Google Play y la compatibilidad con Firebase). La siguiente configuración de ejemplo admite versiones de Android de nivel de API 14 a nivel de API 25:

Compilación mediante el nivel de API 25 Nougat, versión mínima de Android establecida en nivel de API 14

Si la aplicación admite varias versiones de Android, el código debe incluir comprobaciones en tiempo de ejecución para asegurarse de que la aplicación funciona con la configuración de versión mínima de Android (consulte Runtime Checks for Android Versions (Comprobaciones en tiempo de ejecución para versiones de Android ) para obtener más información. Si usa o crea una biblioteca, consulte Los niveles de API y las bibliotecas siguientes para conocer los procedimientos recomendados para configurar las opciones de nivel de API para bibliotecas.

Versiones de Android y niveles de API

A medida que la plataforma Android evoluciona y se publican nuevas versiones de Android, a cada versión de Android se le asigna un identificador entero único, denominado nivel de API. Por lo tanto, cada versión de Android corresponde a un único nivel de API de Android. Dado que los usuarios instalan aplicaciones en versiones anteriores, así como las versiones más recientes de Android, las aplicaciones android reales deben estar diseñadas para funcionar con varios niveles de API de Android.

Versiones de Android

Cada versión de Android va por varios nombres:

  • La versión de Android, como Android 9.0
  • Un nombre de código (o postre), como Pie
  • Un nivel de API correspondiente, como el nivel de API 28

Un nombre de código de Android puede corresponder a varias versiones y niveles de API (como se muestra en la tabla siguiente), pero cada versión de Android corresponde exactamente a un nivel de API.

Además, Xamarin.Android define los códigos de versión de compilación que se asignan a los niveles de API de Android conocidos actualmente. La tabla siguiente puede ayudarle a traducir entre el nivel de API, la versión de Android, el nombre de código y el código de versión de compilación de Xamarin.Android (los códigos de versión de compilación se definen en el Android.OS espacio de nombres):

Nombre Versión Nivel de API Lanzamiento Código de versión de compilación
Q 10.0 29 Agosto de 2020 BuildVersionCodes.Q
Pie 9.0 28 Ago 2018 BuildVersionCodes.P
Oreo 8.1 27 Dic 2017 BuildVersionCodes.OMr1
Oreo 8.0 26 Ago. 2017 BuildVersionCodes.O
Nougat 7.1 25 Diciembre de 2016 BuildVersionCodes.NMr1
Nougat 7.0 24 Ago 2016 BuildVersionCodes.N
Marshmallow 6.0 23 Ago. 2015 BuildVersionCodes.M
Lollipop 5.1 22 Mar. 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 Nov. 2014 BuildVersionCodes.Lollipop
Kitkat Watch 4.4W 20 Junio de 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4. 19 Oct. 2013 BuildVersionCodes.KitKat
Jalea bean 4.3 18 Julio de 2013 BuildVersionCodes.JellyBeanMr2
Jalea bean 4.2-4.2.2 17 Noviembre de 2012 BuildVersionCodes.JellyBeanMr1
Jalea bean 4.1-4.1.1 16 Junio de 2012 BuildVersionCodes.JellyBean
Sándwich helado 4.0.3-4.0.4 15 Dic 2011 BuildVersionCodes.IceCreamSandwichMr1
Sándwich helado 4.0-4.0.2 14 Octubre de 2011 BuildVersionCodes.IceCreamSandwich
Panal 3.2 13 Junio de 2011 BuildVersionCodes.HoneyCombMr2
Panal 3.1.x 12 Mayo de 2011 BuildVersionCodes.HoneyCombMr1
Panal 3.0.x 11 Febrero de 2011 BuildVersionCodes.HoneyComb
Jengibre 2.3.3-2.3.4 10 Febrero de 2011 BuildVersionCodes.GingerBreadMr1
Jengibre 2.3-2.3.2 9 Noviembre de 2010 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 Junio de 2010 BuildVersionCodes.Froyo
Eclair 2.1.x 7 Ene 2010 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 Dic 2009 BuildVersionCodes.Eclair01
Eclair 2.0 5 Noviembre de 2009 BuildVersionCodes.Eclair
Anillo 1.6 4 Septiembre de 2009 BuildVersionCodes.Donut
Magdalena 1.5 3 Mayo de 2009 BuildVersionCodes.Cupcake
Base 1,1 2 Febrero de 2009 BuildVersionCodes.Base11
Base 1.0 1 Octubre de 2008 BuildVersionCodes.Base

Como indica esta tabla, las nuevas versiones de Android se publican con frecuencia, a veces más de una versión al año. Como resultado, el universo de dispositivos Android que podrían ejecutar la aplicación incluye una amplia variedad de versiones anteriores y más recientes de Android. ¿Cómo puedes garantizar que la aplicación se ejecutará de forma coherente y confiable en tantas versiones diferentes de Android? Los niveles de API de Android pueden ayudarle a administrar este problema.

Niveles de API de Android

Cada dispositivo Android se ejecuta exactamente en un nivel de API: se garantiza que este nivel de API es único por cada versión de la plataforma Android. El nivel de API identifica precisamente la versión del conjunto de API al que la aplicación puede llamar; identifica la combinación de elementos de manifiesto, permisos, etc. en el que se codifica como desarrollador. El sistema de niveles de API de Android ayuda a Android a determinar si una aplicación es compatible con una imagen del sistema Android antes de instalar la aplicación en un dispositivo.

Cuando se compila una aplicación, contiene la siguiente información de nivel de API:

  • Nivel de API de destino de Android en el que se compila la aplicación para ejecutarse.

  • El nivel mínimo de API de Android que un dispositivo Android debe tener para ejecutar la aplicación.

Esta configuración se usa para asegurarse de que la funcionalidad necesaria para ejecutar la aplicación está disponible correctamente en el dispositivo Android en el momento de la instalación. Si no es así, se bloquea la ejecución de la aplicación en ese dispositivo. Por ejemplo, si el nivel de API de un dispositivo Android es inferior al nivel de API mínimo que especifique para la aplicación, el dispositivo Android impedirá que el usuario instale la aplicación.

Configuración de nivel de API de project

En las secciones siguientes se explica cómo usar sdk Manager para preparar el entorno de desarrollo para los niveles de API a los que quiere dirigirse, seguido de explicaciones detalladas sobre cómo configurar la versión de Target Framework, la versión mínima de Android y la versión de Android de destino en Xamarin.Android.

Plataformas de Android SDK

Para poder seleccionar un nivel de API de destino o mínimo en Xamarin.Android, debe instalar la versión de la plataforma android SDK correspondiente a ese nivel de API. La gama de opciones disponibles para La plataforma de destino, la versión mínima de Android y la versión de Android de destino se limita a la gama de versiones de Android SDK que ha instalado. Puede usar sdk Manager para comprobar que están instaladas las versiones necesarias de Android SDK y puede usarla para agregar los nuevos niveles de API que necesite para la aplicación. Si no está familiarizado con cómo instalar los niveles de API, consulte Configuración de Android SDK.

Versión de .NET Framework de destino

La plataforma de destino (también conocida como compileSdkVersion) es la versión específica del marco de Android (nivel de API) para la que se compila la aplicación en tiempo de compilación. Esta configuración especifica qué API espera usar la aplicación cuando se ejecuta, pero no tiene ningún efecto en qué API están disponibles realmente para la aplicación cuando se instala. Como resultado, cambiar la configuración de La plataforma de destino no cambia el comportamiento en tiempo de ejecución.

La plataforma de destino identifica las versiones de biblioteca con las que está vinculada la aplicación: esta configuración determina las API que puede usar en la aplicación. Por ejemplo, si desea usar el método NotificationBuilder.SetCategory que se introdujo en Android 5.0 Lollipop, debe establecer la plataforma de destino en nivel de API 21 (Lollipop) o posterior. Si establece la plataforma de destino del proyecto en un nivel de API, como el nivel de API 19 (KitKat) e intenta llamar al método en el SetCategory código, obtendrá un error de compilación.

Se recomienda compilar siempre con la versión más reciente disponible del marco de destino. Al hacerlo, se proporcionan mensajes de advertencia útiles para las API en desuso a las que podría llamar el código. El uso de la versión más reciente de Target Framework es especialmente importante cuando se usan las versiones más recientes de la biblioteca de soporte técnico: cada biblioteca espera que la aplicación se compile en ese nivel de API mínimo o superior de la biblioteca de soporte técnico.

Para acceder a la configuración plataforma de destino en Visual Studio, abra las propiedades del proyecto en Explorador de soluciones y seleccione la página Aplicación:

Página aplicación de propiedades del proyecto

Establezca la plataforma de destino seleccionando un nivel de API en el menú desplegable de Compilar con la versión de Android , como se muestra anteriormente.

Versión mínima de Android

La versión mínima de Android (también conocida como minSdkVersion) es la versión más antigua del sistema operativo Android (es decir, el nivel de API más bajo) que puede instalar y ejecutar la aplicación. De forma predeterminada, una aplicación solo se puede instalar en dispositivos que coincidan con la configuración del marco de destino o superior; si la configuración Versión mínima de Android es inferior a la configuración plataforma de destino, la aplicación también se puede ejecutar en versiones anteriores de Android. Por ejemplo, si establece Target Framework en Android 7.1 (Nougat) y establece la versión mínima de Android en Android 4.0.3 (Ice Cream Sandwich), la aplicación se puede instalar en cualquier plataforma desde el nivel de API 15 hasta el nivel de API 25, ambos incluidos.

Aunque la aplicación puede compilar e instalarse correctamente en esta gama de plataformas, esto no garantiza que se ejecute correctamente en todas estas plataformas. Por ejemplo, si la aplicación está instalada en Android 5.0 (Lollipop) y el código llama a una API que solo está disponible en Android 7.1 (Nougat) y versiones posteriores, la aplicación recibirá un error en tiempo de ejecución y posiblemente se bloqueará. Por lo tanto, el código debe asegurarse , en tiempo de ejecución, de que llama solo a las API compatibles con el dispositivo Android en el que se ejecuta. En otras palabras, el código debe incluir comprobaciones explícitas en tiempo de ejecución para asegurarse de que la aplicación usa api más recientes solo en dispositivos que sean lo suficientemente recientes como para admitirlas. Las comprobaciones en tiempo de ejecución para versiones de Android, más adelante en esta guía, explican cómo agregar estas comprobaciones en tiempo de ejecución al código.

Para acceder a la configuración Versión mínima de Android en Visual Studio, abra las propiedades del proyecto en Explorador de soluciones y seleccione la página Manifiesto de Android. En el menú desplegable en Versión mínima de Android , puede seleccionar la versión mínima de Android para la aplicación:

Opción mínima de Android al destino establecida en Compilar mediante la versión del SDK

Si selecciona Usar compilación con la versión del SDK, la versión mínima de Android será la misma que la configuración de Plataforma de destino.

Versión de Android de destino

La versión de Android de destino (también conocida como targetSdkVersion) es el nivel de API del dispositivo Android donde la aplicación espera ejecutarse. Android usa esta configuración para determinar si se habilitan los comportamientos de compatibilidad, lo que garantiza que la aplicación siga funcionando de la manera esperada. Android usa la configuración de la versión de Android de destino de la aplicación para averiguar qué cambios de comportamiento se pueden aplicar a la aplicación sin interrumpirla (es decir, cómo Android proporciona compatibilidad directa).

La plataforma de destino y la versión de Android de destino, aunque tienen nombres muy similares, no son lo mismo. La configuración de Plataforma de destino comunica la información de nivel de API de destino a Xamarin.Android para su uso en tiempo de compilación, mientras que la versión de Android de destino comunica la información de nivel de API de destino a Android para su uso en tiempo de ejecución (cuando la aplicación está instalada y en ejecución en un dispositivo).

Para acceder a esta configuración en Visual Studio, abra las propiedades del proyecto en Explorador de soluciones y seleccione la página Manifiesto de Android. En el menú desplegable en Versión de Android de destino, puede seleccionar la versión de Android de destino para la aplicación:

Versión de Android de destino establecida en Compilar con la versión del SDK

Se recomienda establecer explícitamente la versión de Android de destino en la versión más reciente de Android que usa para probar la aplicación. Idealmente, debe establecerse en la versión más reciente de Android SDK: esto le permite usar nuevas API antes de trabajar a través de los cambios de comportamiento. Para la mayoría de los desarrolladores, no se recomienda establecer la versión de Android de destino en Usar compilación mediante la versión del SDK.

En general, la versión de Android de destino debe estar limitada por la versión mínima de Android y la plataforma de destino. Es decir:

Versión mínima de <Android = Versión <de Android de destino = Plataforma de destino

Para obtener más información sobre los niveles de SDK, consulte la documentación del desarrollador de Android uses-sdk .

Comprobaciones en tiempo de ejecución para las versiones de Android

A medida que se publica cada nueva versión de Android, la API del marco se actualiza para proporcionar funcionalidades nuevas o de reemplazo. Con pocas excepciones, la funcionalidad de API de versiones anteriores de Android se lleva a cabo en versiones más recientes de Android sin modificaciones. Como resultado, si la aplicación se ejecuta en un nivel de API de Android determinado, normalmente podrá ejecutarse en un nivel posterior de API de Android sin modificaciones. Pero, ¿qué ocurre si también quiere ejecutar la aplicación en versiones anteriores de Android?

Si selecciona una versión mínima de Android inferior a la configuración de Plataforma de destino, es posible que algunas API no estén disponibles para la aplicación en tiempo de ejecución. Sin embargo, la aplicación todavía se puede ejecutar en un dispositivo anterior, pero con una funcionalidad reducida. Para cada API que no está disponible en las plataformas Android correspondientes a la configuración de versión mínima de Android, el código debe comprobar explícitamente el valor de la Android.OS.Build.VERSION.SdkInt propiedad para determinar el nivel de API de la plataforma en la que se ejecuta la aplicación. Si el nivel de API es inferior a la versión mínima de Android que admite la API a la que desea llamar, el código debe encontrar una manera de funcionar correctamente sin realizar esta llamada API.

Por ejemplo, supongamos que queremos usar el método NotificationBuilder.SetCategory para clasificar una notificación cuando se ejecuta en Android 5.0 Lollipop (y versiones posteriores), pero queremos que nuestra aplicación se ejecute en versiones anteriores de Android como Android 4.1 Jelly Bean (donde SetCategory no está disponible). Al principio de esta guía se hace referencia a la tabla de versiones de Android, vemos que el código de versión de compilación para Android 5.0 Lollipop es Android.OS.BuildVersionCodes.Lollipop. Para admitir versiones anteriores de Android donde SetCategory no está disponible, nuestro código puede detectar el nivel de API en tiempo de ejecución y llamar SetCategory condicionalmente solo cuando el nivel de API es mayor o igual que el código de versión de compilación de Lollipop:

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

En este ejemplo, la plataforma de destino de la aplicación se establece en Android 5.0 (nivel de API 21) y su versión mínima de Android se establece en Android 4.1 (nivel de API 16). Dado SetCategory que está disponible en el nivel Android.OS.BuildVersionCodes.Lollipop de API y versiones posteriores, este código de ejemplo llamará SetCategory solo cuando esté disponible, no intentará llamar SetCategory a cuando el nivel de API sea 16, 17, 18, 19 o 20. La funcionalidad se reduce en estas versiones anteriores de Android solo en la medida en que las notificaciones no se ordenan correctamente (porque no están clasificadas por tipo), pero las notificaciones todavía se publican para alertar al usuario. Nuestra aplicación sigue funcionando, pero su funcionalidad se reduce ligeramente.

En general, la comprobación de la versión de compilación ayuda al código a decidir en tiempo de ejecución entre hacer algo nuevo frente a la antigua. Por ejemplo:

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

No hay ninguna regla rápida y sencilla que explique cómo reducir o modificar la funcionalidad de la aplicación cuando se ejecuta en versiones anteriores de Android que carecen de una o varias API. En algunos casos (como en el SetCategory ejemplo anterior), es suficiente omitir la llamada API cuando no está disponible. Sin embargo, en otros casos, es posible que tenga que implementar funcionalidad alternativa para cuando Android.OS.Build.VERSION.SdkInt se detecta que es menor que el nivel de API que la aplicación necesita para presentar su experiencia óptima.

Niveles y bibliotecas de API

Al crear un proyecto de biblioteca de Xamarin.Android (por ejemplo, una biblioteca de clases o una biblioteca de enlaces), solo puede configurar la opción Plataforma de destino: la versión mínima de Android y la configuración de la versión de Android de destino no están disponibles. Esto se debe a que no hay ninguna página de manifiesto de Android :

Solo está disponible la opción Compilar con la versión de Android.

La configuración de la versión mínima de Android y la versión de Android de destino no están disponibles porque la biblioteca resultante no es una aplicación independiente: la biblioteca se puede ejecutar en cualquier versión de Android, en función de la aplicación con la que se empaqueta. Puede especificar cómo se va a compilar la biblioteca, pero no puede predecir en qué nivel de API de plataforma se ejecutará la biblioteca. Teniendo esto en cuenta, se deben observar los siguientes procedimientos recomendados al consumir o crear bibliotecas:

  • Al consumir una biblioteca de Android : si está consumiendo una biblioteca de Android en la aplicación, asegúrese de establecer la configuración del marco de destino de la aplicación en un nivel de API que sea al menos tan alto como la configuración marco de destino de la biblioteca.

  • Al crear una biblioteca de Android : si va a crear una biblioteca de Android para que la usen otras aplicaciones, asegúrese de establecer su configuración de Plataforma de destino en el nivel de API mínimo que necesita para compilar.

Estos procedimientos recomendados se recomiendan para ayudar a evitar la situación en la que una biblioteca intenta llamar a una API que no está disponible en tiempo de ejecución (lo que puede hacer que la aplicación se bloquee). Si es desarrollador de bibliotecas, debe esforzarse por restringir el uso de llamadas API a un subconjunto pequeño y bien establecido del área expuesta de la API total. Esto ayuda a garantizar que la biblioteca se pueda usar de forma segura en una gama más amplia de versiones de Android.

Resumen

En esta guía se explica cómo se usan los niveles de API de Android para administrar la compatibilidad de aplicaciones en diferentes versiones de Android. Se proporcionaron pasos detallados para configurar la plataforma de destino de Xamarin.Android , la versión mínima de Android y la configuración del proyecto de versión de Android de destino . Se proporcionan instrucciones para usar Android SDK Manager para instalar paquetes de SDK, incluidos ejemplos de cómo escribir código para tratar diferentes niveles de API en tiempo de ejecución y se explica cómo administrar los niveles de API al crear o consumir bibliotecas de Android. También proporcionó una lista completa que relaciona los niveles de API con los números de versión de Android (como Android 4.4), los nombres de versión de Android (como Kitkat) y los códigos de versión de compilación de Xamarin.Android.