Xamarin Diplomado | 3.

0
Latinoamrica
Temas selectos de desarrollo mvil en Android

Entendiendo los niveles de API de Android

Xamarin.Android tiene varios niveles de configuracin de APIs Android que determinan la
compatibilidad de una aplicacin con las mltiples versiones de Android.

Xamarin.Android expone 3 configuraciones de proyecto relacionadas con el Nivel de API Android:

Target Framework. Especifica cul Framework utilizar al construir la aplicacin. Este nivel de
API es utilizado en tiempo de compilacin por Xamarin.Android.
Minimum Android Version. Especifica la versin ms antigua de Android que deseamos que
soporte la aplicacin. Este nivel de API es usado en tiempo de ejecucin por Android.
Target Android Version. Especifica la versin de Android en la que se pretende que la
aplicacin se ejecute. Este Nivel de API es usado en tiempo de ejecucin por Android.

Antes de configurar estas propiedades, debemos asegurarnos de haber instalado los paquetes SDK
de Android necesarios para el proyecto.

Normalmente, los tres niveles de API de Xamarin.Android son configurados con el mismo valor.
Primero debemos establecer la opcin Compile using Android versin: (Target Framework) con el
valor de la versin de Android que tenga todas las caractersticas que la aplicacin necesita, despus
debemos establecer las opciones Minimum Android to target y Target Android version con el valor
Use Compile using SDK versin como se muestra en la siguiente imagen.

Si deseamos mantener compatibilidad con versiones anteriores de Android, podemos cambiar la

versin mnima de Android (Minimum Android to target) por el valor de la versin ms antigua de
Android que deseemos que la aplicacin soporte. La siguiente configuracin de ejemplo admite
versiones de Android desde el nivel de API 14 hasta el nivel de API 25 (Android 7.1 Nougat).

Pgina 1 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

Si la aplicacin soporta mltiples versiones de Android, el cdigo de la aplicacin debe incluir

comprobaciones en tiempo de ejecucin para asegurar que la aplicacin funcione con la
configuracin mnima de Android establecida.

Antes de configurar el Nivel de API del proyecto, debemos instalar los componentes del SDK de la
plataforma para ese nivel de API.

Versiones de Android
A medida que la plataforma Android evoluciona, nuevas versiones de Android son liberadas. A cada
versin de Android se le asigna un nmero entero como identificador nico llamado el Nivel de API
(API Level). Debido a que los usuarios instalan aplicaciones tanto en versiones antiguas como en las
versiones ms recientes de Android, las aplicaciones Android del mundo real deben estar diseadas
para trabajar con varios niveles de API de Android.

Cada versin de Android es conocida por diversos nombres:

Por el nivel de API, por ejemplo, API level 14.

Por la versin de Android, por ejemplo, Android 4.0.
Por el nombre de cdigo, por ejemplo, Ice Cream Sandwich.

Adems, Xamarin.Android define los cdigos de versin de compilacin que corresponden con los
niveles de API de Android conocidos. La siguiente lista puede ayudarnos a relacionar entre el Nivel de
API, versin de Android, el nombre cdigo y el cdigo de versin de compilacin de Xamarin.Android.

Nivel Versin de Android Nombre de Fecha de Cdigo de versin de compilacin

de API Cdigo Lanzamiento
API 25 Android 7.1 Nougat Diciembre Android.OS.BuildVersionCodes.NMr1
2016
API 24 Android 7.0 Nougat Agosto 2016 Android.OS.BuildVersionCodes.N
API 23 Android 6.0 Marshmallow Agosto 2015 Android.OS.BuildVersionCodes.M
API 22 Android 5.1 Lollipop Marzo 2015 Android.OS.BuildVersionCodes.LollipopMr1
API 21 Android 5.0 Lollipop Noviembre Android.OS.BuildVersionCodes.Lollipop
2014

Pgina 2 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

API 20 Android 4.4W Kitkat Watch Junio 2014 Android.OS.BuildVersionCodes.KitKatWatch

API 19 Android 4.4 Kitkat Octubre 2013 Android.OS.BuildVersionCodes.KitKat
API 18 Android 4.3 Jelly Bean Julio 2013 Android.OS.BuildVersionCodes.JellyBeanMr2
API 17 Android 4.2-4.2.2 Jelly Bean Noviembre Android.OS.BuildVersionCodes.JellyBeanMr1
2012
API 16 Android 4.1-4.1.1 Jelly Bean Junio 2012 Android.OS.BuildVersionCodes.JellyBean
API 15 Android 4.0.3-4.0.4 Ice Cream Diciembre Android.OS.BuildVersionCodes.IceCreamSandwich
Sandwich 2011
API 14 Android 4.0-4.0.2 Ice Cream Octubre 2011 Android.OS.BuildVersionCodes.IceCreamSandwich
Sandwich
API 13 Android 3.2 Honeycomb Junio 2011 Android.OS.BuildVersionCodes.HoneyCombMr2
API 12 Android 3.1.x Honeycomb Mayo 2011 Android.OS.BuildVersionCodes.HoneyCombMr1
API 11 Android 3.0.x Honeycomb Febrero 2011 Android.OS.BuildVersionCodes.HoneyComb
API 10 Android 2.3.3-2.3.4 Gingerbread Febrero 2011 Android.OS.BuildVersionCodes.GingerBreadMr1
API 9 Android 2.3-2.3.2 Gingerbread Noviembre Android.OS.BuildVersionCodes.GingerBread
2010
API 8 Android 2.2.x Froyo Junio 2010 Android.OS.BuildVersionCodes.Froyo
API 7 Android 2.1.x Eclair Enero 2010 Android.OS.BuildVersionCodes.EclairMr1
API 6 Android 2.0.1 Eclair Diciembre Android.OS.BuildVersionCodes.Eclair01
2009
API 5 Android 2.0 Eclair Noviembre Android.OS.BuildVersionCodes.Eclair
2009
API 4 Android 1.6 Donut Septiembre Android.OS.BuildVersionCodes.Donut
2009
API 3 Android 1.5 Cupcake Mayo 2009 Android.OS.BuildVersionCodes.Cupcake
API 2 Android 1.1 Base Febrero 2009 Android.OS.BuildVersionCodes.Base11
API 1 Android 1.0 Base Octubre 2008 Android.OS.BuildVersionCodes.Base

Como se muestra en la tabla anterior, nuevas versiones de Android son liberadas frecuentemente,
algunas veces hay varias liberaciones por ao. Como resultado, el universo de dispositivos Android
que pueden ejecutar una aplicacin incluye una amplia variedad de antiguas y nuevas versiones de
Android. Cmo podemos garantizar que la aplicacin se ejecute de forma coherente y confiable en
tantas versiones de Android? Los Niveles de API de Android pueden ayudarnos a manejar este
problema.

Niveles de API de Android

Cada dispositivo Android soporta exactamente un nivel de API, este nivel de API es garantizado ser
nico por versin de plataforma Android. El nivel de API identifica exactamente la versin de las
bibliotecas que la aplicacin puede invocar, identifica la combinacin de los elementos del
manifiesto, as como los permisos para los cuales codificamos como desarrolladores. El sistema de
niveles de API de Android ayuda a Android a determinar si una aplicacin es compatible con una
imagen de sistema Android antes de instalar la aplicacin en un dispositivo. Cuando una aplicacin
es creada, esta contiene la siguiente informacin de nivel de API:

Pgina 3 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

El nivel de API de Android destino con el que la aplicacin fue compilada para su ejecucin.
El nivel mnimo de API de Android que es requerido para ejecutar la aplicacin.

Esta configuracin se utiliza para garantizar que la funcionalidad necesaria para ejecutar
correctamente la aplicacin est disponible en el dispositivo Android en el momento de la
instalacin. De lo contrario, la aplicacin no se ejecutar en ese dispositivo. Por ejemplo, si el nivel de
API de un dispositivo Android es menor que el nivel mnimo de API que hayamos especificado en la
aplicacin, el dispositivo Android evitar que el usuario instale la aplicacin.

Configuracin del Nivel de API de un proyecto

Antes de poder seleccionar un nivel de API mnimo o destino en Xamarin.Android, debemos instalar
la versin de Android SDK correspondiente a ese nivel de API. La lista de opciones disponibles para
establecer el valor del Framework destino, la versin mnima de Android y la versin destino de
Android est limitada al rango de versiones de SDK de Android que hayamos instalado. Podemos
utilizar el Administrador de SDK de Android (Android SDK Manager) para verificar que las versiones
de SDK de Android requeridas estn instaladas y tambin para agregar los nuevos niveles de API que
necesitemos para nuestra aplicacin.

Compile using Android versin: (Target Framework)

La opcin Target Framework especifica la versin del Framework de Android (nivel de API) en que la
aplicacin es compilada. Esta configuracin especfica las APIs que la aplicacin espera utilizar
durante se ejecucin, pero no tiene efecto sobre cuales APIs se encuentran disponibles para la
aplicacin cuando esta es instalada. Las opciones Target Framework y Target Android version,
aunque tienen nombres muy similares, no son la misma cosa. La opcin Target Framework comunica
la informacin de nivel de API destino a Xamarin.Android para que la utilice en tiempo de
compilacin, mientras que la opcin Target Android versin comunica la informacin de nivel de API
destino a Android para su uso en tiempo de ejecucin (cuando la aplicacin est instalada y
ejecutndose en un dispositivo).

La opcin Target Framework identifica cuales son las versiones de bibliotecas sobre las cuales est
enlazada la aplicacin, esto determina las APIs que podemos utilizar en la aplicacin. Por ejemplo, si
deseamos utilizar un mtodo Notification.Builder.SetCategory que fue introducido en la versin de
Android 5.0 Lollipop, debemos establecer el Target Framework en el nivel de API 21 (Lollipop). Si
establecemos la opcin Target Framework del proyecto a un nivel de API como el nivel de API 19
(KitKat) e intentamos invocar al mtodo SetCategory en el cdigo, obtendremos un error de
compilacin.

Pgina 4 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

Minimum Android to target

La opcin Minumum Android to target especifica la versin ms antigua de Android (el nivel menor
de API) en el que se puede instalar y ejecutar la aplicacin. De forma predeterminada, una aplicacin
slo se puede instalar en dispositivos que coincidan con la configuracin del Target Framework o
superior. Si la configuracin de la versin mnima de Android es inferior a la configuracin del Target
Framework, la aplicacin tambin podr ser ejecutada en versiones anteriores de Android. Por
ejemplo, si establecemos el Target Framework en Android 5.0 Lollipop y establecemos la versin
mnima de Android en Android 4.4 (API 19 Kit Kat), la aplicacin se puede instalar en cualquier
plataforma desde el nivel de API 19 hasta el nivel de API 21 incluso.

Aunque la aplicacin se puede crear e instalar correctamente en este rango de plataformas, esto no
garantiza que se ejecute correctamente en todas estas plataformas. Por ejemplo, si la aplicacin est
instalada en Android 4.4 (API 19 Kit Kat) y el cdigo invoca a una API que slo est disponible en
Android 5.0 (Lollipop) o posteriores, la aplicacin tendr un error en tiempo de ejecucin y
posiblemente se cerrar.

Por lo tanto, el cdigo debe garantizar que, en tiempo de ejecucin, slo invoque a las APIs que son
soportadas por el dispositivo Android en el que se est ejecutando. En otras palabras, el cdigo debe
incluir comprobaciones explcitas en tiempo de ejecucin para garantizar que la aplicacin utiliza APIs
ms recientes slo en dispositivos que sean lo suficientemente nuevos como para soportarlas.

Si seleccionamos la opcin Use Compile using SDK versin, la versin mnima de Android ser la
misma que la configurada en la opcin Compile using Android versin: (Target Framework).

Target Android Version

La opcin Target Android Version es el nivel de API del dispositivo Android en el que la aplicacin
espera ejecutarse. Android utiliza esta configuracin para determinar si debe habilitar algn
comportamiento de compatibilidad para garantizar que la aplicacin contine funcionando como es
esperado.

Pgina 5 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

Normalmente, el valor de Target Android version debe establecerse en Use Compile using SDK
Version, para que el valor coincida automticamente con la configuracin del Target Framework.

En general, el valor de Target Android version debe estar limitado entre el valor de Minumum
Android to target y el valor de Target Framework. Es decir:

Minumum Android to target <= Target Android version <= Target Framework

Comprobacion de Versiones de Android en tiempo de ejecucin

A medida que se publica cada nueva versin de Android, la API del Framework es actualizada para
proporcionar funcionalidad nueva o de reemplazo. Con pocas excepciones, la funcionalidad de las
APIs de las versiones anteriores de Android es llevada a las versiones ms recientes de Android sin
modificaciones. Como resultado, si la aplicacin se ejecuta en un nivel determinado de API de
Android, normalmente podr ejecutarse en un nivel posterior de API de Android sin modificaciones.
Pero Qu pasa si tambin queremos ejecutar la aplicacin en versiones anteriores de Android?

Si seleccionamos una versin mnima de Android que sea menor a la configuracin del Target
Framework, es posible que algunas APIs no estn disponibles para la aplicacin en tiempo de
ejecucin. Sin embargo, la aplicacin an podra ejecutarse en un dispositivo anterior, pero con una
funcionalidad reducida.

Para cada API que no est disponible en las plataformas Android que correspondan a la configuracin
mnima de versin de Android, el cdigo de la aplicacin debe comprobar explcitamente el valor de
la propiedad Android.OS.Build.VERSION.SdkInt para determinar el nivel de API de la plataforma en
la que se est ejecutando la aplicacin. Si el nivel de la API es inferior a la versin mnima de Android
que admite la API que deseamos invocar, el cdigo tiene que encontrar una forma de funcionar
correctamente sin realizar esa llamada a la API.

Por ejemplo, supongamos que queremos utilizar el nuevo mtodo Notification.Builder.SetCategory

para categorizar una notificacin cuando se ejecuta en Android 5.0 Lollipop (y posterior), pero
tambin queremos que nuestra aplicacin se ejecute en versiones anteriores de Android como
Android 4.1 Jelly Bean, donde SetCategory no est disponible. Haciendo referencia a la tabla de
versin de Android, vemos que el cdigo de versin de compilacin para Android 5.0 Lollipop es
Android.OS.BuildVersionCodes.Lollipop. Para soportar versiones anteriores de Android donde
SetCategory no est disponible, nuestro cdigo puede detectar el nivel de API en tiempo de
ejecucin y condicionalmente llamar a SetCategory slo cuando el nivel de API es mayor o igual al
cdigo de versin de compilacin Lollipop:

if (Android.OS.Build.VERSION.SdkInt >= BuildVersionCodes.Lollipop)

{
// Esta versin de Android soporta SetCategory.
}
else

Pgina 6 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

{
// Esta versin de Android NO soporta SetCategory

En este ejemplo, el valor de Target Framework de la aplicacin es establecido en Android 5.0 (nivel
de API 21) y la versin mnima de Android es establecida en Android 4.4 (Nivel de API 19). Debido a
que SetCategory est disponible en el nivel de API Android.OS.BuildVersionCodes.Lollipop y
posteriores, el cdigo del ejemplo invocar a SetCategory slo cuando est realmente disponible y no
intentar llamar a SetCategory cuando el nivel de la API sea 19 o 20. La funcionalidad se reduce en las
versiones anteriores de Android slo en la medida en que las notificaciones no se ordenaran
correctamente (porque no se clasifican por categora), pero las notificaciones seguiran publicndose
para alertar al usuario. La aplicacin seguira funcionando, pero su funcionalidad estara ligeramente
disminuida.

En general, la verificacin de la versin de compilacin ayuda a que el cdigo pueda decidir en

tiempo de ejecucin entre hacer algo de la nueva forma o hacerlo a de la vieja manera.

No existe una regla simple y rpida que explique cmo reducir o modificar la funcionalidad de la
aplicacin cuando se ejecute en versiones anteriores de Android que carecen de una o ms APIs. En
algunos casos (como en el ejemplo SetCategory anterior), es suficiente simplemente omitir la
llamada a la API cuando no est disponible. Sin embargo, en otros casos, es posible que deba
implementar una funcionalidad alternativa para cuando Android.OS.Build.VERSION.SdkInt detecte
que es menor que el nivel de API que la aplicacin necesita para presentar una experiencia ptima.

Niveles de API y Librerias

Cuando creamos un proyecto de biblioteca de Xamarin.Android (como un Class Library o un Bindings
Library), podemos configurar nicamente el valor de Target Framework, las opciones Minumum
Android to target y Target Android version no se encuentran disponibles.

Pgina 7 de 8 http://ticapacitacion.com/curso/xamarin30
 Xamarin Diplomado | 3.0
Latinoamrica
Temas selectos de desarrollo mvil en Android

Las opciones Minumum Android to target y Target Android version se omitieron porque la biblioteca
resultante no es una aplicacin independiente. La biblioteca podra ejecutarse en cualquier versin
de Android, dependiendo de la aplicacin con la que est empaquetada. Podemos especificar cmo
se va a compilar la biblioteca, pero no podemos predecir en qu nivel de plataforma API ser
ejecutada la biblioteca. Teniendo esto en cuenta, deben observarse las siguientes prcticas
recomendadas al consumir o crear bibliotecas:

Al consumir una biblioteca de Android. Si la aplicacin consume una biblioteca de Android,

debes asegrate de establecer la configuracin del Target Framework de la aplicacin en un
nivel de API que sea por lo menos igual de alto que el Target Framework de la biblioteca.
Al crear una biblioteca Android. Si ests creando una biblioteca de Android para usarla en
otras aplicaciones, asegrate de establecer la configuracin de Target Framework en el nivel
de API mnimo que necesita para compilar.

Estas buenas prcticas son recomendadas para evitar la situacin en que una biblioteca intente
invocar a una API que no est disponible en tiempo de ejecucin (lo que puede provocar que la
aplicacin se bloquee). Si eres un desarrollador de bibliotecas, debes esforzarte por restringir el uso
de las llamadas API a un conjunto pequeo y bien establecido del rea total de la API. Hacer eso
ayuda a asegurar que tu biblioteca se pueda utilizar de forma segura en una amplia gama de
versiones de Android.

Pgina 8 de 8 http://ticapacitacion.com/curso/xamarin30