Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

<uses-sdk>

Google Play usa los atributos <uses-sdk> declarados en el manifiesto de tu aplicación 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" />
contenido en:
<manifest>
descripción:

Te permite expresar la compatibilidad de una aplicación con una o más versiones de la plataforma 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 o 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 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.

Advertencia: 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 API 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 se bloqueará durante el tiempo de ejecución al intentar acceder a las API 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 dirige la aplicación. Si no se configura, el valor predeterminado es igual al valor asignado a la minSdkVersion.

Este atributo informa al sistema que has realizado las pruebas en la versión prevista y el sistema no deberá habilitar ningún comportamiento de compatibilidad a fin de mantener la compatibilidad con versiones posteriores de tu aplicación y la versión prevista. 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 aplicación, el sistema podrá habilitar comportamientos de compatibilidad a fin de garantizar que tu aplicación 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 habilita 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 definiste para este atributo. Varios de estos comportamientos se describen mediante las versiones de plataforma correspondientes en la referencia Build.VERSION_CODES.

A fin de 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.

Presentado en: 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, esto elimina 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 aplicación. Al cabo de algunas semanas, el usuario recibe una actualización del sistema a Android 2.0 (nivel de API 5) de manera inalámbrica. 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 elimina del dispositivo.

Advertencia: No se recomienda declarar este atributo. En primer lugar, no es necesario definir el atributo implementando el bloqueo 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 compatibles con versiones anteriores. Tu aplicación debería funcionar correctamente en versiones nuevas, dado que solo usa API 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.

Presentado en: 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.
presentado en:
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 marco de trabajo que ofrece una versión de la plataforma de Android.

La plataforma de Android proporciona una API de marco de trabajo que las aplicaciones pueden usar para interactuar con el sistema de Android subyacente. La API de marco de trabajo 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 cumplimientos de permisos incluidos en el sistema

Cada versión sucesiva de la plataforma de Android puede incluir actualizaciones a la API de marco de trabajo de aplicaciones de Android que ofrece.

Las actualizaciones a la API de marco de trabajo 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 eliminan, de modo que las aplicaciones existentes aún puedan usarlas. En unos pocos casos, las partes de la API pueden modificarse o eliminarse, si bien, 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 marco de trabajo 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 es compatible exactamente con 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 compatible con 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.

Versión de la plataformaNivel de APIVERSION_CODENotas
Android Q Beta 29 Q Información destacada de la plataforma
Android 9 28 P Información destacada de la plataforma
Android 8.1 27 O_MR1 Información destacada de la plataforma
Android 8.0 26 O Información destacada de la plataforma
Android 7.1.1
Android 7.1
25 N_MR1 Información destacada de la plataforma
Android 7.0 24 N Información destacada de la plataforma
Android 6.0 23 M Información destacada de la plataforma
Android 5.1 22 LOLLIPOP_MR1 Información destacada de la plataforma
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat solo para wearables
Android 4.4 19 KITKAT Información destacada de la plataforma
Android 4.3 18 JELLY_BEAN_MR2 Información destacada de la plataforma
Android 4.2 y 4.2.2 17 JELLY_BEAN_MR1 Información destacada de la plataforma
Android 4.1 y 4.1.1 16 JELLY_BEAN Información destacada de la plataforma
Android 4.0.3 y 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Información destacada de la plataforma
Android 4.0, 4.0.1 y 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 Información destacada de la plataforma
Android 3.0.x 11 HONEYCOMB Información destacada de la plataforma
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Información destacada de la plataforma
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Información destacada de la plataforma
Android 2.1.x 7 ECLAIR_MR1 Información destacada de la plataforma
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Información destacada de la plataforma
Android 1.5 3 CUPCAKE Información destacada de la plataforma
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Usos del nivel de API en Android

El identificador del nivel de API tiene un papel clave a la hora de 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 marco de trabajo máxima que esta admite.
  • Permite que la aplicación describa la revisión de la API de marco de trabajo 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 marco de trabajo (<uses-sdk>) a fin de 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, esto le permite a la aplicación utilizar elementos del manifiesto o comportamientos definidos en el nivel de API de destino, en vez 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: Consulta la documentación sobre <uses-sdk> antes de utilizar este atributo.

Por ejemplo, a fin de 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 la 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 acerca de 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 API 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 API 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 presentó con el nivel de API 3. Si una aplicación usa esa API, debe declarar un atributo android:minSdkVersion con el valor "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).

Para obtener más información sobre cómo 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 marco de trabajo se agregan, una aplicación de 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 elimina 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.

Compatibilidad de la aplicación con versiones anteriores

Las aplicaciones de Android no tienen necesariamente compatibilidad con versiones anteriores de las versiones de la plataforma de Android más antigua que la versión en la cual se compilaron.

Cada versión nueva de la plataforma de Android puede incluir nuevas API de marco de trabajo, 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 API 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 especificado por el nivel de API. Por otro lado, debido a que las versiones anteriores de la plataforma no incluyen las API nuevas, las aplicaciones que usan dichas API nuevas no pueden ejecutarse en tales 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 tu aplicación 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 API 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 API 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 de esta. En este último caso, la aplicación se bloqueará en el tiempo de ejecución cuando intente usar API 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, a fin de 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 a esta herramienta, usa la herramienta de línea de comandos android que se encuentra 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 la documentación de referencia del sitio para desarrolladores de Android ofrecen un control de "filtro por nivel de API" en la esquina superior derecha 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, fija el control de "filtro por nivel de API" en el mismo nivel de API que el especificado por tu aplicación. Ten en cuenta que las API presentadas en un nivel de API posterior quedan inhabilitadas y su contenido es enmascarado, ya que tu aplicación no podrá acceder a estas.

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, inhabilita la función mediante la casilla de verificación. Según la configuración predeterminada, el filtrado por nivel de API está inhabilitado, de modo que puedas ver la API de marco de trabajo completa, independientemente 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 la documentación. El nivel de API para miembros de clase se especifica en sus encabezados de descripción detallada, en el margen derecho.