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 lo que 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 opciones 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 está pensada que se ejecute 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 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 tengan 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 más información, consulte Requisitos de nivel de API de destino para Play Console en "Creación y configuración de 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 siguiente captura de pantalla, la plataforma de destino se establece en Android 7.1 (nivel API 25: Nougat):

Target Framework version defaults to Compile using Android version

En la página Manifiesto de Android, establezca la versión mínima de Android en Usar compilación mediante 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 de destino de Android se establece en Android 7.1 (Nougat)):

Minimum and Target Android versions set to Target Framework version

Si quiere mantener la compatibilidad con versiones anteriores de Android, establezca la opción Versión mínima de Android como destino a la versión más antigua de Android que quiere 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:

Compile using API level 25 Nougat, Minimum Android version set to API level 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 funcione con la configuración de la versión mínima de Android (consulte Comprobaciones en tiempo de ejecución para versiones de Android a continuación para obtener más información). Si usa o crea una biblioteca, consulte los niveles de API y bibliotecas que se indican a continuación para conocer los procedimientos recomendados para configurar la configuración de nivel de API para las bibliotecas.

Versiones de Android y niveles de API

A medida que evoluciona la plataforma Android y se publican nuevas versiones de Android, a cada versión 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 del mundo real deben diseñarse para trabajar con varios niveles de API de Android.

Versiones de Android

Cada versión de Android recibe 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 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 espacio de nombres Android.OS):

Nombre Versión Nivel de API Publicado Código de versión de compilación
Q 10.0 29 Agosto de 2020 BuildVersionCodes.Q
Circular 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 Agosto de 2016 BuildVersionCodes.N
Marshmallow 6.0 23 Agosto de 2015 BuildVersionCodes.M
Lollipop 5,1 22 Marzo de 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 Nov. 2014 BuildVersionCodes.Lollipop
Kitkat Watch 4.4W 20 Jun 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4. 19 Octubre de 2013 BuildVersionCodes.KitKat
Jelly Bean 4.3 18 Jul 2013 BuildVersionCodes.JellyBeanMr2
Jelly Bean 4.2-4.2.2 17 Noviembre de 2012 BuildVersionCodes.JellyBeanMr1
Jelly Bean 4.1-4.1.1 16 Junio de 2012 BuildVersionCodes.JellyBean
Ice Cream Sandwich 4.0.3-4.0.4 15 Diciembre de 2011 BuildVersionCodes.IceCreamSandwichMr1
Ice Cream Sandwich 4.0-4.0.2 14 Oct 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
Gingerbread 2.3.3-2.3.4 10 Febrero de 2011 BuildVersionCodes.GingerBreadMr1
Gingerbread 2.3-2.3.2 9 Nov 2018 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 Diciembre de 2009 BuildVersionCodes.Eclair01
Eclair 2.0 5 Noviembre de 2009 BuildVersionCodes.Eclair
Anillo 1.6 4 Septiembre de 2009 BuildVersionCodes.Donut
Cupcake 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

Tal como se indica en 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ía ejecutar la aplicación incluye una amplia variedad de versiones anteriores y más recientes de Android. ¿Cómo puede 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 resolver 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 sea único por versión de 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 los que se codifica como desarrollador. El sistema 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 para el que se ha creado la aplicación.

  • 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 impide que la aplicación se ejecute en ese dispositivo. Por ejemplo, si el nivel de API de un dispositivo Android es inferior al nivel de API mínimo que haya especificado para la aplicación, el dispositivo Android impedirá que el usuario instale la aplicación.

Configuración de nivel de API de proyecto

En las secciones siguientes se explica cómo usar el Administrador de SDK 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 plataforma de destino, la versión mínima de Android y la configuración de la versión de Android de destino en Xamarin.Android.

Plataformas de Android SDK

Para poder seleccionar un nivel de API de destino o el nivel de API mínimo en Xamarin.Android, debe instalar la versión de la plataforma Android SDK correspondiente a ese nivel de API. El rango 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 al intervalo de versiones de Android SDK que ha instalado. Puede usar el Administrador de SDK para comprobar que están instaladas las versiones necesarias de Android SDK y puede usarlo para agregar los nuevos niveles de API que necesite para la aplicación. Si no está familiarizado con cómo instalar niveles de API, consulte Configuración de Android SDK.

Marco 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 realmente disponibles para la aplicación cuando se instala. Como resultado, cambiar la configuración de la plataforma de destino no cambia el comportamiento del entorno de ejecución.

La plataforma de destino identifica las versiones de biblioteca con las que está vinculada la aplicación: esta configuración determina qué API puede usar en la aplicación. Por ejemplo, si quiere 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 SetCategory en el código, obtendrá un error de compilación.

Se recomienda compilar siempre con la versión más reciente disponible de plataforma de destino. Si lo hace, proporciona mensajes de advertencia útiles para cualquier API en desuso a las que pueda llamar el código. El uso de la versión más reciente de la plataforma de destino 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 de la plataforma de destino en Visual Studio, abra las propiedades del proyecto en el Explorador de soluciones y seleccione la página Aplicación:

Application page of project Properties

Para establecer la plataforma de destino, seleccione un nivel de API en el menú desplegable en Compilar con la versión de Android, como se ha mostrado 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 de la plataforma de destino o versiones superiores; si la configuración de la versión mínima de Android es inferior a la configuración de la plataforma de destino, la aplicación también se puede ejecutar en versiones anteriores de Android. Por ejemplo, si establece la plataforma de destino 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 este rango 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 más recientes, la aplicación obtendrá un error en tiempo de ejecución y posiblemente se bloqueará. Por lo tanto, el código debe asegurarse de que, en tiempo de ejecución, 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 las API más recientes solo en los dispositivos que son lo suficientemente recientes como para admitirlas. La sección Comprobaciones en tiempo de ejecución para versiones de Android, más adelante en esta guía, explica cómo agregar estas comprobaciones en tiempo de ejecución al código.

Para acceder a la configuración de la versión mínima de Android en Visual Studio, abra las propiedades del proyecto en el 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:

Minimum Android to target option set to Compile using SDK version

Si selecciona Usar compilar con la versión del SDK, la versión mínima de Android será la misma que la configuración de la 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 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 (así es como Android proporciona compatibilidad con versiones posteriores).

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 la 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 se instala y se ejecuta en un dispositivo).

Para acceder a esta configuración en Visual Studio, abra las propiedades del proyecto en el 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 de la aplicación:

Target Android version set to Compile using SDK version

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 con 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 enlazada 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 más información sobre los niveles del SDK, consulte la documentación de Android Developer uses-sdk.

Comprobaciones en tiempo de ejecución para versiones de Android

A medida que se publica cada nueva versión de Android, la API de marco se actualiza para proporcionar una funcionalidad nueva 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 de API de Android posterior 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 la 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 propiedad Android.OS.Build.VERSION.SdkInt 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 tiene que 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 aún 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 a SetCategory condicionalmente solo cuando el nivel de API sea 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 que SetCategory está disponible en el nivel de API Android.OS.BuildVersionCodes.Lollipop y versiones posteriores, este código de ejemplo solo llamará a SetCategory cuando esté disponible realmente, no intentará llamar a SetCategory 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 se clasifican 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 de la forma nueva o de la forma 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 ejemplo anterior de SetCategory), es suficiente omitir la llamada API cuando no está disponible. Sin embargo, en otros casos, es posible que deba implementar una funcionalidad alternativa para cuando se detecta Android.OS.Build.VERSION.SdkInt que es menor que el nivel de API que la aplicación necesita para presentar su experiencia óptima.

Niveles de API y bibliotecas

Al crear un proyecto de biblioteca de Xamarin.Android (por ejemplo, una biblioteca de clases o una biblioteca de enlaces), solo puede configurar el valor de la 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:

Only the Compile using Android version option is available

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 usa una biblioteca de Android en la aplicación, asegúrese de establecer la configuración de la plataforma de destino de la aplicación en un nivel de API que sea al menos tan alto como la configuración de la plataforma de destino de la biblioteca.

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

Estos procedimientos recomendados se aconsejan 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 un rango más amplio de versiones de Android.

Resumen

En esta guía se ha explicado cómo se usan los niveles de API de Android para administrar la compatibilidad de aplicaciones en distintas versiones de Android. Se han proporcionado los 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 han proporcionado instrucciones para usar Android SDK Manager para instalar paquetes de SDK, se han incluido ejemplos de cómo escribir código para tratar diferentes niveles de API en tiempo de ejecución y se ha explicado cómo administrar los niveles de API al crear o consumir bibliotecas de Android. También se ha proporcionado 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.