<uses-sdk>

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 que expresa una aplicación se compara con el nivel de API de un sistema de Android determinado, que 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 kit de desarrollo de software (SDK) 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 aplicación. El sistema de Android impide que el usuario instale la aplicación si el nivel de API del sistema es inferior al valor especificado en este atributo. Declara siempre 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 no lo es, y no declaraste la minSdkVersion correcta, la aplicación fallará cuando se instale en un sistema con un nivel de API incompatible durante el tiempo de ejecución cuando intente 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 orienta 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 habilita ningún comportamiento de compatibilidad para mantener la compatibilidad con versiones posteriores de tu aplicación y la versión objetivo. La aplicación aún puede ejecutarse en versiones anteriores (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 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 el tema predeterminado Holo a tu app 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, aumenta el valor de este atributo para que coincida con el nivel de API más reciente y, luego, prueba por completo tu aplicación en la versión de la plataforma correspondiente.

Se introdujo 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 no permite 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 ejecuta 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 recomendamos 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 publican. Gracias a su diseño, las versiones nuevas de la plataforma son totalmente retrocompatibles. Tu aplicación funciona correctamente en versiones nuevas, siempre y cuando solo use APIs estándar y siga las prácticas recomendadas de desarrollo. En segundo lugar, 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 forma inalámbrica; por eso, ten en cuenta su efecto en tu aplicación antes de definir este atributo.

Se introdujo en el nivel de API 4.

Algunas versiones de Android (posteriores a Android 2.0.1) no verifican ni aplican 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 ellos
• 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 se modifican o se quitan, aunque, por lo general, tales cambios solo son necesarios para admitir 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 con 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 (hasta el nivel 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 el panel de distribución.

Usos del nivel de API en Android

El identificador del nivel de API es clave para garantizar la mejor 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 las aplicaciones describan la revisión de la API de framework que requieren.
• Permite que el sistema negocie la instalación de aplicaciones en el dispositivo del usuario para 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 el nivel de API preferido con el cual tienen compatibilidad por diseño. El elemento ofrece tres atributos clave:

• android:minSdkVersion: Especifica el nivel de API mínimo en el cual puede ejecutarse la aplicación. El valor predeterminado es "1".
• android:targetSdkVersion: Especifica el nivel de API en el cual la aplicación está diseñada para ejecutarse. En algunos casos, esto permite que la aplicación use elementos del manifiesto o comportamientos definidos en el nivel de API objetivo, en lugar de limitarse a utilizar solo aquellos definidos para el nivel de API mínimo.
• android:maxSdkVersion: Especifica el nivel de API máximo en el cual puede ejecutarse la aplicación. Importante: Antes de usarlo, consulta la información sobre este atributo.

Por ejemplo, para especificar el nivel de API mínimo del sistema que requiere una aplicación para poder ejecutarse, esta incluye en su manifiesto un elemento <uses-sdk> con un atributo android:minSdkVersion. El valor de android:minSdkVersion es el valor entero que corresponde al nivel de API de la primera versión de la plataforma de Android en la cual puede 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 es menor o igual que el 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 es 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. Lee la descripción de este atributo para obtener más información sobre el modo en que controla el sistema.

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>

El motivo principal por el que una aplicación declara un nivel de API en android:minSdkVersion es para indicarle al sistema Android que usa las APIs que se presentaron en el nivel de API especificado.

Si la aplicación se instala de alguna manera en una plataforma con un nivel de API inferior, fallará durante el tiempo de ejecución cuando intente acceder a las APIs que no existen. El sistema evita este resultado porque no permite que la aplicación se instale si el nivel de API mínimo requerido es superior al de la versión de la plataforma del dispositivo de destino.

Consideraciones de desarrollo

En las siguientes secciones, se proporciona información relacionada con el nivel de API que debes tener en cuenta cuando desarrollas tu aplicación.

Compatibilidad de la aplicación con versiones posteriores

Por lo general, las aplicaciones para 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 con una versión determinada de la API, según lo que especifica 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 puede ejecutarse en todas las versiones más recientes de la plataforma de Android, excepto en casos aislados en los que 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ía instalar tu aplicación y usarla con éxito, y, luego, recibir una actualización OTA a una versión nueva de la plataforma de Android. Una vez que se instala la actualización, tu aplicación se ejecuta en una nueva versión de tiempo de ejecución del entorno, pero que sigue teniendo las capacidades de sistema y de API de las que depende.

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. Es importante para ti, como desarrollador de la aplicación, comprender el aspecto y el comportamiento que esta tiene en cada entorno del sistema.

Para 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 la 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, además, cuando se ejecutan en versiones más recientes de la plataforma, según lo que especifique el nivel de API. Sin embargo, debido a que las versiones anteriores de la plataforma no incluyen las APIs nuevas, las aplicaciones que usan dichas APIs no pueden ejecutarse en esas plataformas.

Aunque es probable que un dispositivo con Android no se cambie a una versión inferior de la plataforma, es importante tener en cuenta que seguramente haya numerosos dispositivos en el campo que ejecutan versiones más antiguas de la plataforma. Incluso entre los dispositivos que reciben actualizaciones OTA, pueden existir algunos con retraso que no reciban una actualización durante un plazo considerable.

Cómo seleccionar una versión de plataforma y un nivel de API

Cuando desarrollas tu aplicación, debes elegir la versión de la plataforma en la cual compilarás la aplicación. En general, la compilarás 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, crea un AVD con la versión de la plataforma y el nivel de API correspondientes, y prueba 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.

Cómo declarar 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, define el atributo android:minSdkVersion en el nivel de API de la versión de la plataforma más reciente. De esta forma, los usuarios solo podrán instalar tu aplicación si sus dispositivos ejecutan una versión compatible de la plataforma de Android. A su vez, esto ayuda a garantizar 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 falla en el tiempo de ejecución cuando intenta usar APIs que no existen en las versiones anteriores.

Cómo realizar pruebas con niveles de API más altos

Después de compilar tu aplicación, asegúrate 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 comprobar la compatibilidad con versiones futuras, ejecuta y prueba 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 ejecutar android sdk para iniciar la herramienta de actualización de SDK. También puedes hacer doble clic en el archivo android.bat (Windows) o android (OS X/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 AVDs, consulta Cómo crear y administrar 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 en este documento para conocer una lista de las versiones de plataforma y sus niveles de API.

Cómo filtrar 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 puede acceder tu aplicación, según el nivel de API que especifica en el atributo android:minSdkVersion de su archivo de manifiesto.

Para usar el filtrado, selecciona el nivel de API que especificó tu aplicación en el menú. Las APIs presentadas en un nivel de API posterior quedan inhabilitadas, y su contenido se enmascara, ya que tu aplicación no puede 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; 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.

Para volver a ver la documentación completa, selecciona REL en la parte superior del menú de nivel de API. 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.

En la documentación de referencia de los elementos individuales de la API, se especifica el nivel de API en el cual se presentó cada elemento. El nivel de API para paquetes y clases se especifica como "Se agregó en el 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.