Google Play usa los atributos <uses-sdk> declarados en el manifiesto de tu app para aplicar filtros y excluir dispositivos que no cumplan con los requisitos de la versión de su plataforma. Antes de definir estos atributos, asegúrate de comprender los filtros de Google Play.

sintaxis:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

se incluye en:

<manifest>

descripción:

Te permite expresar la compatibilidad de una aplicación con una o más versiones de la plataforma de Android, a través de un valor entero de nivel de API. El nivel de API expresado por una aplicación se comparará con el nivel de API de un sistema de Android determinado, el cual puede variar según los diferentes dispositivos Android.

Más allá de su nombre, este elemento se usa para especificar el nivel de API, no el número de la versión del SDK (kit de desarrollo de software) o la plataforma de Android. El nivel de API siempre es un entero único. No puedes derivar el nivel de API de su número de versión de Android asociado (por ejemplo, no es igual a la versión principal ni a la suma de las versiones principal y secundaria).

Consulta también el documento sobre el control de versiones de tus aplicaciones.

atributos:

android:minSdkVersion

Valor entero que designa el nivel de API mínimo que se requiere para que se ejecute la app. El sistema de Android impedirá que el usuario instale la aplicación si el nivel de API del sistema es inferior al valor especificado en este atributo. Siempre debes declarar este atributo.

Precaución: Si no declaras este atributo, el sistema adopta un valor predeterminado igual a "1", el cual indica que tu aplicación es compatible con todas las versiones de Android. Si tu aplicación no es compatible con todas las versiones (por ejemplo, usa APIs presentadas en el nivel de API 3) y no declaraste la minSdkVersion adecuada, cuando se realice la instalación en un sistema con un nivel de API inferior a 3, la aplicación fallará durante el tiempo de ejecución al intentar acceder a las APIs no disponibles. Por este motivo, asegúrate de declarar el nivel de API adecuado en el atributo minSdkVersion.

android:targetSdkVersion

Valor entero que designa el nivel de API al cual se segmenta la aplicación. Si no se configura, el valor predeterminado es igual al valor asignado a la minSdkVersion.

Este atributo informa al sistema que realizaste las pruebas en la versión prevista y el sistema no deberá habilitar ningún comportamiento de compatibilidad para mantener la compatibilidad con versiones posteriores de tu aplicación y la versión objetivo. La aplicación puede continuar ejecutándose en versiones más antiguas (anteriores a la minSdkVersion).

Debido a que Android evoluciona con cada versión nueva, algunos comportamientos e incluso algunas apariencias pueden cambiar. Sin embargo, si el nivel de API de la plataforma es superior a la versión declarada por la targetSdkVersion de tu app, el sistema podrá habilitar comportamientos de compatibilidad para garantizar que tu app continúe funcionando de la manera esperada. Puedes inhabilitar tales comportamientos de compatibilidad si especificas que la targetSdkVersion coincida con el nivel de API de la plataforma en la cual se ejecuta. Por ejemplo, configurar este valor en "11" o en un valor superior permite que el sistema aplique un nuevo tema predeterminado (Holo) en tu aplicación cuando se ejecuta en Android 3.0 o versiones posteriores, y también inhabilita el modo de compatibilidad de pantalla con pantallas de mayor tamaño (porque la compatibilidad del nivel de API 11 implícitamente admite pantallas más grandes).

Existen numerosos comportamientos de compatibilidad que el sistema puede habilitar según el valor que definas para este atributo. Varios de estos comportamientos se describen por las versiones de plataforma correspondientes en la referencia Build.VERSION_CODES.

Para mantener tu aplicación junto con cada versión de Android, debes aumentar el valor de este atributo para que coincida con el nivel de API más reciente y, luego, probar por completo tu aplicación en la versión de la plataforma correspondiente.

Se introdujo este atributo en el nivel de API 4.

android:maxSdkVersion

Valor entero que designa el nivel de API máximo en el cual la aplicación está diseñada para ejecutarse.

En Android 1.5, 1.6, 2.0 y 2.0.1, el sistema verifica el valor de este atributo cuando se instala una aplicación y cuando se vuelve a validar después de una actualización del sistema. En cualquier caso, si el atributo maxSdkVersion de la aplicación es inferior al nivel de API que usa el propio sistema, este último no permitirá que se instale la aplicación. En el caso de una nueva validación tras una actualización del sistema, se quita de manera efectiva tu aplicación del dispositivo.

Para ilustrar la manera en que este atributo puede influir en tu aplicación después de las actualizaciones del sistema, ten presente el siguiente ejemplo:

Se publica en Google Play una aplicación que declara la maxSdkVersion="5" en su manifiesto. Un usuario cuyo dispositivo se ejecuta en Android 1.6 (nivel de API 4) descarga e instala la app. Después de unas semanas, el usuario recibe una actualización del sistema inalámbrica a Android 2.0 (nivel de API 5). Después de que se instala la actualización, el sistema verifica la maxSdkVersion de la aplicación y la vuelve a validar con éxito. La aplicación funciona normalmente. Sin embargo, después de un tiempo, el dispositivo recibe otra actualización del sistema, esta vez, a Android 2.0.1 (nivel de API 6). Después de la actualización, el sistema no puede volver a validar la aplicación porque el propio nivel de API (6) del sistema ahora es superior al valor máximo admitido por la aplicación (5). El sistema impide que el usuario vea la aplicación; de hecho, la quita del dispositivo.

Advertencia: No se recomienda declarar este atributo. En primer lugar, no es necesario definir el atributo para bloquear la implementación de tu aplicación en versiones nuevas de la plataforma de Android a medida que se publiquen. Gracias a su diseño, las versiones nuevas de la plataforma son totalmente retrocompatibles. Tu aplicación debería funcionar correctamente en versiones nuevas, dado que solo usa APIs estándares y sigue las prácticas recomendadas de desarrollo. En segundo lugar, ten presente que, en algunos casos, la declaración del atributo puede ocasionar la eliminación de tu aplicación de los dispositivos de los usuarios después de una actualización del sistema a un nivel de API superior. La mayoría de los dispositivos en los cuales probablemente se instale tu aplicación recibirán actualizaciones de sistema periódicas de manera inalámbrica; por eso, debes tener en cuenta su efecto en tu aplicación antes de definir este atributo.

Se introdujo este atributo en el nivel de API 4.

Las versiones futuras de Android (posteriores a Android 2.0.1) dejarán de verificar o controlar el atributo maxSdkVersion durante la instalación o la nueva validación. Sin embargo, Google Play continuará usando el atributo como filtro en el momento de presentar a los usuarios las aplicaciones disponibles para descargar.

primera inclusión:

Nivel de API 1

¿Qué es el nivel de API?

El nivel de API es un valor entero que identifica de manera única la revisión de la API de framework ofrecida por una versión de la plataforma de Android.

La plataforma de Android proporciona una API de framework que las aplicaciones pueden usar para interactuar con el sistema de Android subyacente. La API de framework consta de lo siguiente:

• Un conjunto básico de paquetes y clases
• Un conjunto de atributos y elementos XML para declarar un archivo de manifiesto
• Un conjunto de atributos y elementos XML para declarar recursos y acceder a estos
• Un conjunto de intents
• Un conjunto de permisos que las aplicaciones pueden solicitar, al igual que aplicaciones de permisos incluidos en el sistema

Cada versión sucesiva de la plataforma de Android puede incluir actualizaciones a la API de framework de aplicaciones de Android que entrega.

Las actualizaciones a la API de framework están diseñadas de modo tal que la nueva API continúe siendo compatible con las versiones de API anteriores. Es decir, la mayoría de los cambios en la API se agregan y presentan funcionalidades nuevas o de reemplazo. Debido a que se actualizan partes de la API, las partes más antiguas reemplazadas dejan de estar disponibles, pero no se quitan, de modo que las aplicaciones existentes aún puedan usarlas. En unos pocos casos, las partes de la API pueden modificarse o quitarse, aunque, por lo general, tales cambios solo son necesarios para garantizar la solidez de la API y la seguridad de la aplicación o del sistema. Todas las demás partes de la API de las revisiones anteriores se llevan adelante sin modificaciones.

La API de framework que ofrece una plataforma de Android se especifica mediante un identificador de valor entero llamado "nivel de API". Cada versión de la plataforma de Android admite exactamente un nivel de API, si bien la compatibilidad está implícita para todos los niveles de API anteriores (inferiores al 1). En la versión inicial de la plataforma de Android, se ofreció un nivel de API 1 y, en las posteriores, el nivel aumentó.

En la siguiente tabla, se especifica el nivel de API que admite cada versión de la plataforma de Android. Para obtener información sobre los números relativos de dispositivos en los cuales se ejecuta cada versión, consulta la página de paneles de versiones de la plataforma.

Usos del nivel de API en Android

El identificador del nivel de API es fundamental para garantizar la mejor experiencia posible para los usuarios y los desarrolladores de aplicaciones:

• Permite que la plataforma de Android describa la revisión de la API de framework máxima que esta admite.
• Permite que la aplicación describa la revisión de la API de framework que se requiere.
• Permite que el sistema negocie la instalación de aplicaciones en el dispositivo del usuario, de modo que no se instalen aplicaciones incompatibles con la versión.

Cada versión de la plataforma de Android almacena su identificador de nivel de API de manera interna, en el propio sistema de Android.

Las aplicaciones pueden usar un elemento de manifiesto proporcionado por la API de framework (<uses-sdk>) para describir los niveles de API mínimo y máximo dentro de los cuales pueden ejecutarse, así como también el nivel de API preferido con el cual tienen compatibilidad por diseño. El elemento ofrece tres atributos clave:

• android:minSdkVersion, que especifica el nivel de API mínimo en el cual puede ejecutarse la aplicación. El valor predeterminado es "1".
• android:targetSdkVersion, que especifica el nivel de API en el cual la aplicación está diseñada para ejecutarse. En algunos casos, le permite a la aplicación utilizar elementos del manifiesto o comportamientos definidos en el nivel de API objetivo, en lugar de limitarse a utilizar únicamente aquellos definidos por el nivel mínimo de API.
• android:maxSdkVersion, que especifica el nivel de API máximo en el cual puede ejecutarse la aplicación. Importante: Lee la documentación sobre <uses-sdk> antes de usar el atributo.

Por ejemplo, para especificar el nivel de API mínimo del sistema que requiere una aplicación para poder ejecutarse, en el manifiesto de la aplicación debe incluirse un elemento <uses-sdk> con un atributo android:minSdkVersion. El valor de android:minSdkVersion debe ser un valor entero que corresponda al nivel de API de la primera versión de la plataforma de Android en la cual pueda ejecutarse la aplicación.

Cuando el usuario intenta instalar una aplicación o cuando se vuelve a validar una aplicación después de una actualización del sistema, en primer lugar, el sistema de Android verifica los atributos <uses-sdk> del manifiesto de la aplicación y compara los valores con su propio nivel de API interno. El sistema permite que se inicie la instalación solo si se cumplen las siguientes condiciones:

• Si se declara un atributo android:minSdkVersion, su valor debe ser menor o igual que el valor entero del nivel de API del sistema. Si no se declara, el sistema da por sentado que la aplicación requiere un nivel de API 1.
• Si se declara un atributo android:maxSdkVersion, su valor debe ser igual o mayor que el entero del nivel de API del sistema. Si no se declara, el sistema da por sentado que la aplicación no presenta un nivel de API máximo. Consulta la documentación sobre <uses-sdk> para obtener más información sobre la manera en que el sistema controla este atributo.

Cuando se declara en el manifiesto de una aplicación, un elemento <uses-sdk> tiene el siguiente aspecto:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Una aplicación debe declarar un nivel de API en android:minSdkVersion principalmente para indicar al sistema de Android que se emplean APIs presentadas en el nivel de API especificado. Si la aplicación se instalara en una plataforma con un nivel de API inferior, se bloquearía en el tiempo de ejecución cuando intentara acceder a las APIs que no existen. El sistema evita ese resultado al no permitir que la aplicación se instale si el nivel de API requerido es superior a la versión de la plataforma del dispositivo de destino.

Por ejemplo, el paquete android.appwidget se introdujo con el nivel de API 3. Si una aplicación usa esa API, debe declarar un atributo android:minSdkVersion con un valor de "3". La aplicación podrá instalarse en plataformas como Android 1.5 (nivel de API 3) y Android 1.6 (nivel de API 4), pero no en las plataformas Android 1.1 (nivel de API 2) o Android 1.0 (nivel de API 1).

Si deseas obtener más información para especificar los requisitos del nivel de API de una aplicación, consulta la sección <uses-sdk> de la documentación del archivo de manifiesto.

Consideraciones de desarrollo

En las secciones siguientes, se brinda información relacionada con el nivel de API que debes tener en cuenta en el momento de desarrollar tu aplicación.

Compatibilidad de la aplicación con versiones posteriores

Por lo general, las aplicaciones de Android tienen compatibilidad con versiones futuras de las nuevas versiones de la plataforma de Android.

Debido a que casi todos los cambios en la API de framework se agregan, una aplicación para Android desarrollada mediante una versión determinada de la API (según lo especificado por su nivel de API) tiene compatibilidad con versiones futuras de las versiones más recientes de la plataforma de Android y con niveles de API superiores. La aplicación debe poder ejecutarse en todas las versiones más recientes de la plataforma de Android, excepto en casos aislados en los cuales la aplicación usa una parte de la API que más tarde se quita por algún motivo.

La compatibilidad con versiones posteriores resulta importante porque numerosos dispositivos con tecnología Android reciben actualizaciones del sistema de manera inalámbrica (OTA). El usuario podrá instalar tu aplicación y usarla con éxito y, posteriormente, recibir una actualización inalámbrica a una versión nueva de la plataforma de Android. Una vez que se instale la actualización, tu aplicación se ejecutará en una nueva versión de tiempo de ejecución del entorno, aunque esta deberá contar con capacidades de sistema y de API de las cuales dependa tu aplicación.

En algunos casos, los cambios por debajo de la API, como aquellos en el propio sistema subyacente, pueden afectar tu aplicación cuando se ejecuta en el entorno nuevo. Por ese motivo, es importante para ti, como desarrollador de la aplicación, comprender el aspecto y el comportamiento que esta tendrá en cada entorno del sistema. A fin de ayudarte a probar tu aplicación en diferentes versiones de la plataforma de Android, el SDK de Android incluye varias plataformas que puedes descargar. Cada una contiene una imagen de sistema compatible que puedes ejecutar en un AVD para probar tu aplicación.

Retrocompatibilidad de la aplicación

Las aplicaciones para Android no necesariamente tienen retrocompatibilidad con versiones de la plataforma de Android más antiguas que la versión en la cual se compilaron.

Cada versión nueva de la plataforma de Android puede incluir nuevas APIs de framework, como aquellas que otorgan a las aplicaciones acceso a nuevas capacidades de la plataforma o reemplazan partes de la API existente. Las aplicaciones pueden acceder a las nuevas APIs cuando se ejecutan en la plataforma nueva y, como se mencionó antes, también cuando se ejecutan en versiones más recientes de la plataforma, según lo que especifique el nivel de API. Por otro lado, debido a que las versiones anteriores de la plataforma no incluyen las APIs nuevas, las aplicaciones que usan dichas APIs nuevas no pueden ejecutarse en esas plataformas.

Si bien es poco probable que un dispositivo con tecnología Android pase a una versión anterior de la plataforma, es importante tener en cuenta que probablemente existan numerosos dispositivos que se ejecuten en versiones anteriores de la plataforma. Incluso entre los dispositivos que reciben actualizaciones inalámbricas, pueden existir algunos con retraso que no reciban una actualización durante un plazo considerable.

Selección de una versión de plataforma y un nivel de API

Cuando desarrolles tu aplicación, deberás elegir la versión de la plataforma en la cual compilarás la aplicación. En general, deberás compilar tu aplicación en la versión más antigua posible de la plataforma que pueda admitir.

Para determinar la versión más antigua posible de la plataforma, puedes crear la aplicación con orientaciones de compilación cada vez más antiguas. Después de determinar la versión más antigua, debes crear un AVD con la versión de la plataforma correspondiente (y el nivel de API) y probar por completo tu aplicación. Asegúrate de declarar un atributo android:minSdkVersion en el manifiesto de la aplicación y fijar su valor en el nivel de API de la versión de la plataforma.

Declaración de un nivel de API mínimo

Si compilas una aplicación que usa APIs o funciones del sistema presentadas en la versión de la plataforma más reciente, debes definir el atributo android:minSdkVersion en el nivel de API de la versión de la plataforma más reciente. Esto garantiza que los usuarios solo puedan instalar tu aplicación si los dispositivos se ejecutan en una versión compatible de la plataforma de Android. A su vez, esto garantiza que tu aplicación pueda funcionar correctamente en sus dispositivos.

Si tu aplicación usa APIs presentadas en la versión de la plataforma más reciente, pero no declara un atributo android:minSdkVersion, se ejecutará correctamente en dispositivos con la versión más reciente de la plataforma, pero no en dispositivos con las versiones anteriores. En este último caso, la aplicación fallará en el tiempo de ejecución cuando intente usar APIs que no existan en las versiones anteriores.

Pruebas en niveles de API superiores

Después de compilar tu aplicación, debes asegurarte de probarla en la plataforma especificada en el atributo android:minSdkVersion de la aplicación. Para hacerlo, crea un AVD que use la versión de la plataforma que requiera tu aplicación. Además, para garantizar la compatibilidad con versiones futuras, debes ejecutar y probar la aplicación en todas las plataformas que usen un nivel de API superior al de tu aplicación.

El SDK de Android incorpora varias versiones de la plataforma que puedes usar, incluida la más reciente, y ofrece una herramienta de actualización que puedes emplear para descargar otras versiones de la plataforma según sea necesario.

Para acceder al actualizador, usa la herramienta de línea de comandos de android, ubicada en el directorio <sdk>/tools. Puedes iniciar la herramienta de actualización de SDK ejecutando android sdk. También puedes hacer doble clic en el archivo android.bat (Windows) o android (OS X o Linux).

Para ejecutar tu aplicación con diferentes versiones de la plataforma en el emulador, crea un AVD para cada versión de la plataforma que desees probar. Para obtener más información sobre los AVD, consulta la sección Creación y administración de dispositivos virtuales. Si usas un dispositivo físico para las pruebas, asegúrate de conocer el nivel de API de la plataforma de Android en la cual se ejecuta. Consulta la tabla al principio de este documento para conocer una lista de las versiones de plataforma y sus niveles de API.

Filtrado de la documentación de referencia por nivel de API

Las páginas de documentación de referencia de la plataforma de Android ofrecen un control de "Nivel de API" en el área superior izquierda de cada página. Puedes usar el control para mostrar solo la documentación de las partes de la API a las cuales realmente pueda acceder tu aplicación, según el nivel de API que se especifica en el atributo android:minSdkVersion de su archivo de manifiesto.

Si deseas usar el filtrado, selecciona la casilla de verificación para habilitarlo debajo del cuadro de búsqueda de la página. Luego, configura el control de "Filtro por nivel de API" en el mismo nivel de API que especificó tu aplicación. Ten en cuenta que las APIs presentadas en un nivel de API posterior quedan inhabilitadas y su contenido es enmascarado, ya que tu aplicación no podrá acceder a ellas.

El filtrado por nivel de API en la documentación no ofrece una vista de lo nuevo o lo presentado en cada nivel de API; simplemente, proporciona una manera de ver toda la API asociada con un nivel de API determinado y, al mismo tiempo, excluye los elementos de API presentados en los niveles de API posteriores.

Si decides que no deseas filtrar la documentación de la API, usa la casilla de verificación para inhabilitar la función. De forma predeterminada, el filtrado por nivel de API está inhabilitado, de modo que puedas ver la API de framework completa, más allá del nivel de API.

Ten presente que, además, la documentación de referencia de elementos individuales de la API especifica el nivel de API en el cual se presentó cada elemento. El nivel de API para paquetes y clases se especifica como "desde <nivel de API>" en la esquina superior derecha del área de contenido de cada página de documentación. El nivel de API para miembros de clase se especifica en sus encabezados de descripción detallada, en el margen derecho.