Skip to content

Most visited

Recently visited

navigation

<uses-sdk>

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 de Android, por medio 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 app, el sistema podrá habilitar comportamientos de compatibilidad a fin de 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 app 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 en cuenta 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. 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 la aplicación sea visible para el usuario; 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 lancen. 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 en cuenta 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 al 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 Framework API que ofrece una versión de la plataforma de Android.

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

Cada versión sucesiva de la plataforma de Android puede incluir actualizaciones a la Android Application Framework API que ofrece.

Las actualizaciones a la Framework API 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 un pequeño número de 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 Framework API 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 aumentó el nivel de API.

En la tabla siguiente 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 7.0 24 N Funciones destacadas de la plataforma
Android 6.0 23 M Funciones destacadas de la plataforma
Android 5.1 22 LOLLIPOP_MR1 Funciones destacadas de la plataforma
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat para wearables únicamente
Android 4.4 19 KITKAT Funciones destacadas de la plataforma
Android 4.3 18 JELLY_BEAN_MR2 Funciones destacadas de la plataforma
Android 4.2 y 4.2.2 17 JELLY_BEAN_MR1 Funciones destacadas de la plataforma
Android 4.1 y 4.1.1 16 JELLY_BEAN Funciones destacadas de la plataforma
Android 4.0.3 y 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Funciones destacadas 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 Funciones destacadas de la plataforma
Android 3.0.x 11 HONEYCOMB Funciones destacadas de la plataforma
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Funciones destacadas de la plataforma
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Funciones destacadas de la plataforma
Android 2.1.x 7 ECLAIR_MR1 Funciones destacadas de la plataforma
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Funciones destacadas de la plataforma
Android 1.5 3 CUPCAKE Funciones destacadas 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:

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 Framework API (<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 claves:

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:

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: no permite 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 un valor igual a “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 de Android 1.1 (nivel de API 2) y 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 al 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 Framework API 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 más tarde 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 Android SDK 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 Framework API, 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. Opcionalmente, 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. Aun entre los dispositivos que reciben actualizaciones inalámbricas, pueden existir algunos que representen un retraso y no reciban una actualización durante un período de tiempo 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 sucesivamente 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 creas 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 más elevados

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 más elevado que el de tu aplicación.

El Android SDK 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>/herramientas. 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 (SO 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 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 de los 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 estos.

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 Framework API completa, independientemente del nivel de API.

Ten en cuenta, además, que 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 <api level>” 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.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.