sintaxe:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
contido em:
<manifest>
descrição:

Permite expressar a compatibilidade de um aplicativo com uma ou mais versões da plataforma Android por meio de um número inteiro de nível de API. O nível da API expresso por um aplicativo será comparado ao nível da API de determinado sistema Android, que pode variar entre diversos dispositivos Android.

Apesar do nome, esse elemento é usado para especificar o nível da API e não o número da versão do SDK (kit de desenvolvimento de software) ou da plataforma Android. O nível da API é sempre um número inteiro simples. Não é possível deduzir o nível da API usando o número de versão do Android associado (por exemplo, ele não é igual à versão principal ou à soma de versões principais e secundárias).

Leia também o documento sobre Criação de versões de aplicativos.

atributos:
android:minSdkVersion
Um inteiro designando o nível mínimo de API necessário para a execução do aplicativo. O sistema Android evitará que o usuário instale o aplicativo se o nível da API do sistema for inferior ao valor especificado nesse atributo. Esse atributo deve ser sempre declarado.

Atenção: Se você não declarar esse atributo, o sistema usará o valor padrão de "1", indicando que o aplicativo é compatível com todas as versões do Android. Se o aplicativo não for compatível com todas as versões (por exemplo, ele usa as APIs introduzidas na API de nível 3) e você não declarou o minSdkVersion correto, o aplicativo falhará durante o tempo de execução quando tentar acessar APIs não disponíveis se instalado em sistemas com um nível de API inferior a 3. Por esse motivo, não deixe de declarar o nível de API correto no atributo minSdkVersion.

android:targetSdkVersion
Um inteiro que indica o nível de API para o qual o aplicativo é direcionado. Se não definido, o valor padrão é o mesmo definido em minSdkVersion.

Esse atributo informa ao sistema que o aplicativo foi testado na versão direcionada e que o sistema não deve ativar nenhum comportamento de compatibilidade para manter a compatibilidade do aplicativo com versões futuras na versão direcionada. O aplicativo pode ainda ser executado em versões anteriores (até minSdkVersion).

À medida que o Android evolui para novas versões, alguns comportamentos, e até mesmo aparências, podem mudar. No entanto, se o nível de API da plataforma for maior que a versão declarada na targetSdkVersion do aplicativo, o sistema poderá ativar comportamentos de compatibilidade para garantir que o aplicativo continue a funcionar da maneira esperada. Você pode desativar esses comportamentos de compatibilidade especificando uma targetSdkVersion correspondente ao nível de API da plataforma onde o aplicativo é executado. Por exemplo, a definição desse valor como "11" ou maior permite que o sistema aplique um novo tema padrão (Holo) ao aplicativo quando executado no Android 3.0 ou posterior e desative o modo de compatibilidade de tela quando executado em telas maiores (pois o a API de nível 11 permite implicitamente telas maiores).

Há muitos comportamentos de compatibilidade que podem ser ativados pelo sistema de acordo com o valor definido nesse atributo. Vários desses comportamentos são descritos pelas versões correspondentes da plataforma na referência Build.VERSION_CODES.

Para manter o aplicativo juntamente com cada versão do Android, você deve aumentar o valor desse atributo para corresponder ao nível de API mais recente e executar um teste completo do aplicativo na versão de plataforma correspondente.

Introduzido na: API de nível 4

android:maxSdkVersion
Um inteiro que define o nível máximo de API para o qual o aplicativo foi projetado para executar.

No Android 1.5, 1.6, 2.0 e 2.0.1, o sistema verifica o valor desse atributo ao instalar um aplicativo e ao revalidar o aplicativo após uma atualização do sistema. Nos dois casos, se o atributo maxSdkVersion do aplicativo for menor que o nível de API usado pelo próprio sistema, o sistema não permitirá que a instalação do aplicativo. Na revalidação depois de uma atualização do sistema, o aplicativo será removido do dispositivo.

Para mostrar como esse atributo pode afetar o aplicativo após atualizações do sistema, considere o exemplo a seguir:

Um aplicativo declarando maxSdkVersion="5" em seu manifesto é publicado no Google Play. Um usuário com dispositivo executando Android 1.6 (API de nível 4) baixa e instala o aplicativo. Depois de algumas semanas, o usuário recebe uma atualização do sistema remota para o Android 2.0 (API de nível 5). Após a instalação da atualização, o sistema verifica o maxSdkVersion do aplicativo e o revalida. O aplicativo funciona normalmente. No entanto, algum tempo depois, o dispositivo recebe outra atualização do sistema, desta vez para o Android 2.0.1 (API de nível 6). Após a atualização, o sistema não consegue mais revalidar o aplicativo, pois o nível de API do sistema (6) passou a ser maior que o máximo permitido pelo aplicativo (5). O sistema evita que o aplicativo fique visível para o usuário, removendo-o do dispositivo.

Aviso: Não recomendamos a declaração desse atributo. Primeiro, não há necessidade de definir o atributo como um meio de bloquear a implantação do aplicativo em novas versões da plataforma Android à medida que são lançadas. Por projeto, as novas versões da plataforma são totalmente compatíveis com versões anteriores. O aplicativo deve funcionar corretamente com novas versões, desde que use apenas APIs padrão e siga as práticas recomendadas de desenvolvimento. Segundo, observe que, em alguns casos, a declaração do atributo pode resultar na remoção do aplicativo dos dispositivos do usuário após uma atualização do sistema para uma API de nível superior. A maioria dos dispositivos onde o aplicativo provavelmente será instalado receberá remotamente atualizações de sistema periódicas. Portanto, você deve considerar seu efeito no aplicativo antes de definir esse atributo.

Introduzido na: API de nível 4

Versões futuras do Android (posteriores ao Android 2.0.1) não verificarão ou aplicarão o atributo maxSdkVersion durante a instalação ou revalidação. No entanto, o Google Play continuará a usar o atributo como filtro ao apresentar aos usuários os aplicativos disponíveis para baixar.
introduzido na:
API de nível 1

O que é um nível de API?

O nível da API é um valor inteiro que identifica unicamente a revisão da API da estrutura de trabalho oferecida por uma versão da plataforma Android.

A plataforma Android oferece uma API de estrutura de trabalho que pode ser usada pelos aplicativos para interagir com o sistema Android subjacente. A API da estrutura de trabalho consiste em:

  • Um conjunto principal de pacotes e classes
  • Um conjunto de elementos e atributos XML para declarar um arquivo de manifesto
  • Um conjunto de elementos e atributos XML para declarar e acessar recursos
  • Um conjunto de intents
  • Um conjunto de permissões que podem ser solicitadas pelos aplicativos, bem como a aplicação das permissões inclusas no sistema

Cada versão sucessiva da plataforma Android pode conter atualizações para a API da estrutura de trabalho de aplicativos Android que fornece.

As atualizações da API da estrutura de trabalho são projetadas de forma a manter a compatibilidade da nova API com suas versões anteriores. Ou seja, a maioria das mudanças na API são incrementais e introduzem funcionalidades novas ou atualizadas. À medida que partes da API são atualizadas, as partes substituídas são consideradas obsoletas, mas não são removidas, permitindo que os aplicativos existentes continuem a usá-las. Em um número muito reduzido de casos, partes da API podem ser modificadas ou removidas, embora normalmente essas mudanças sejam necessárias apenas para garantir a robustez da API e a segurança do aplicativo ou sistema. Todas as outras partes das API de revisões anteriores são propagadas sem modificação.

A API da estrutura de trabalho fornecida por uma plataforma Android é especificada por um identificador inteiro denominado "nível de API". Cada versão da plataforma Android permite exatamente um nível de API, embora todos níveis anteriores de API (até o nível de API 1) sejam implicitamente permitidos. A versão inicial da plataforma Android forneceu a API de nível 1 e as versões subsequentes incrementaram esse nível.

A tabela abaixo especifica o nível de API permitido em cada versão da plataforma Android. Para obter informações sobre as quantidades relativas de dispositivos que executam cada versão, consulte a página de painéis de versões de plataforma.

Versão da plataformaNível de APIVERSION_CODEObservações
Android 7.0 24 N Destaques da plataforma
Android 6.0 23 M Destaques da plataforma
Android 5.1 22 LOLLIPOP_MR1 Destaques da plataforma
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat somente para wearables
Android 4.4 19 KITKAT Destaques da plataforma
Android 4.3 18 JELLY_BEAN_MR2 Destaques da plataforma
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 Destaques da plataforma
Android 4.1, 4.1.1 16 JELLY_BEAN Destaques da plataforma
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Destaques da plataforma
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 Destaques da plataforma
Android 3.0.x 11 HONEYCOMB Destaques da plataforma
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Destaques da plataforma
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Destaques da plataforma
Android 2.1.x 7 ECLAIR_MR1 Destaques da plataforma
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Destaques da plataforma
Android 1.5 3 CUPCAKE Destaques da plataforma
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Usos de nível de API no Android

O identificador de nível de API desempenha um papel essencial para garantir a melhor experiência possível para usuários e desenvolvedores de aplicativos:

  • Permite que a plataforma Android descreva a revisão máxima de estrutura de trabalho de API compatível
  • Permite que os aplicativos descrevam a revisão de API de estrutura de trabalho exigida
  • Permite que o sistema negocie a instalação de aplicativos no dispositivo do usuário para impedir a instalação de aplicativos com versões incompatíveis.

Cada versão da plataforma Android armazena seu identificador de nível de API internamente, no próprio sistema Android.

Os aplicativos podem usar um elemento de manifesto fornecido pela API da estrutura de trabalho — <uses-sdk> — para descrever os níveis mínimo e máximo de API onde podem ser executados, bem como o nível de API preferencial para o qual foram projetados. O elemento oferece três atributos principais:

  • android:minSdkVersion — Especifica o nível de API mínimo no qual o aplicativo pode ser executado. O valor padrão é "1".
  • android:targetSdkVersion — Especifica o nível da API no qual o aplicativo foi projetado para executar. Em alguns casos, isso permite que o aplicativo use elementos do manifesto ou comportamentos definidos no nível da API de destino em vez de ser restringido a usar somente aqueles definidos para o nível mínimo da API.
  • android:maxSdkVersion — Especifica o nível de API máximo no qual o aplicativo pode ser executado. Importante: Leia a documentação <uses-sdk> antes de usar esse atributo.

Por exemplo, para especificar o nível mínimo de API de sistema exigido para a execução do aplicativo, o manifesto deve conter um elemento <uses-sdk> com um atributo android:minSdkVersion. O valor de android:minSdkVersion é o inteiro correspondente ao nível de API da versão mais antiga da plataforma Android onde o aplicativo pode ser executado.

Quando o usuário tentar instalar um aplicativo, ou quando o aplicativo for revalidado após uma atualização do sistema, o sistema Android verificará primeiro os atributos <uses-sdk> no manifesto do aplicativo e comparará os valores com o seu próprio nível de API interno. O sistema somente permite o início da instalação se estas condições forem respeitadas:

  • Se um atributo android:minSdkVersion for declarado, seu valor deverá ser menor ou igual ao inteiro de nível de API do sistema. Se não declarado, o sistema entenderá que o aplicativo exibe a API de nível 1.
  • Se um atributo android:maxSdkVersion for declarado, seu valor deve ser igual ou maior ao inteiro de nível de API do sistema. Se não declarado, o sistema entenderá que o aplicativo não tem um nível máximo de API. Leia a documentação de <uses-sdk> para obter mais informações sobre como o sistema processa esse atributo.

Quando declarado em um manifesto do aplicativo, um elemento <uses-sdk> pode ter a seguinte aparência:

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

O motivo principal para que um aplicativo declare um nível de API usando android:minSdkVersion é informar o sistema Android de que usa APIs que foram introduzidas no nível de API especificado. Se o aplicativo fosse de alguma forma instalado em uma plataforma com um nível de API inferior, falharia em tempo de execução quando tentasse acessar APIs inexistentes. O sistema evita esse problema impedindo a instalação do aplicativo se o nível mínimo de API exigido for maior que o da versão da plataforma no dispositivo de destino.

Por exemplo, o pacote android.appwidget foi introduzido com a API de nível 3. Se um aplicativo usar essa API, deverá declarar um atributo android:minSdkVersion com um valor de "3". O aplicativo será então instalado em plataformas como Android 1.5 (API de nível 3) e Android 1.6 (API de nível 4), mas não nas plataformas Android 1.1 (API de nível 2) e Android 1.0 (API de nível 1).

Para obter mais informações sobre como especificar os requisitos de nível de API do aplicativo, consulte a seção <uses-sdk> da documentação do arquivo de manifesto.

Considerações de desenvolvimento

As seções abaixo oferecem informações relacionadas ao nível de API que você deve considerar ao desenvolver seu aplicativo.

Compatibilidade com versões futuras

Normalmente, os aplicativos Android são compatíveis com versões futuras da plataforma Android.

Como praticamente todas as mudanças na API da estrutura de trabalho são incrementais, um aplicativo Android desenvolvido usando qualquer versão da API (conforme especificado pelo seu nível de API) é compatível com versões posteriores da plataforma Android e níveis superiores de API. O aplicativo deve ser capaz de executar em todas as versões posteriores da plataforma Android, exceto em casos isolados em que o aplicativo usa uma parte da API que é removida posteriormente por algum motivo.

A compatibilidade com versões futuras é importante porque muitos dispositivos que executam Android recebem atualizações do sistema remotamente (OTA). O usuário pode instalar o aplicativo, usá-lo de forma bem-sucedida e receber posteriormente uma atualização OTA para uma nova versão da plataforma Android. Após a instalação da atualização, o aplicativo executará em uma nova versão de tempo de execução do ambiente. No entanto, essa versão terá os recursos de API e sistema necessários para o aplicativo.

Em alguns casos, alterações abaixo da API, como as no próprio sistema subjacente, podem afetar o aplicativo quando executado no novo ambiente. Por esse motivo, é importante que você, como desenvolvedor do aplicativo, entenda qual será a aparência e o comportamento do aplicativo nesse ambiente de sistema. Para ajudá-lo a testar o aplicativo nas diversas versões da plataforma Android, o Android SDK contém várias plataformas disponíveis para baixar. Cada plataforma inclui uma imagem de sistema compatível que pode ser executada em um AVD para testar o aplicativo.

Compatibilidade com versões anteriores

Os aplicativos Android não são necessariamente compatíveis com versões anteriores da plataforma Android mais antigas que a versão utilizada para a compilação.

Cada versão nova da plataforma Android pode conter novas APIs de estrutura de trabalho, como as que permitem que aplicativos acessem os novos recursos da plataforma ou as que substituem partes de APIs existentes. As novas APIs podem ser acessadas pelos aplicativos quando executados na nova plataforma e também, como mencionado acima, quando executados em versões posteriores da plataforma, conforme a especificação do nível de API. Da mesma forma, como versões anteriores da plataforma não contêm as novas APIs, os aplicativos que usam as novas APIs não podem ser executados nessas plataformas.

Embora seja pouco provável que um dispositivo com Android faça downgrade para uma versão anterior da plataforma, é importante notar que podem existir muitos dispositivos em campo executando versões anteriores da plataforma. Mesmo entre dispositivos que recebem atualizações OTA, alguns podem demorar a ser atualizados e é possível que não recebam a atualização por um período considerável.

Selecionar uma versão de plataforma e um nível de API

Ao desenvolver o aplicativo, será necessário escolher a versão da plataforma na qual você compilará o aplicativo. De forma geral, você deve compilar o aplicativo usando a menor versão de plataforma possível com a qual o aplicativo deve ser compatível.

Você pode determinar a menor versão de plataforma possível compilando o aplicativo para versões sucessivamente menores. Depois de determinar a menor versão, você deve criar um AVD usando a versão de plataforma (e nível de API) correspondentes e executar um teste completo do aplicativo. Não deixe de declarar um atributo android:minSdkVersion no manifesto do aplicativo e definir seu valor para o nível de API da versão da plataforma.

Declarar um nível mínimo de API

Se você criar um aplicativo que usa APIs ou recursos de sistema introduzidos na versão de plataforma mais recente, defina o atributo android:minSdkVersion como o nível de API dessa versão de plataforma mais recente. Isso garante que os usuários somente poderão instalar o aplicativo se os dispositivos executarem uma versão compatível da plataforma do Android. Por outro lado, isso garante que o aplicativo poderá funcionar adequadamente nos dispositivos.

Se o aplicativo usar APIs introduzidas na versão mais recente na plataforma, mas não declarar um atributo android:minSdkVersion, ele será executado corretamente em dispositivos com a versão mais recente da plataforma, mas não em dispositivos com versões anteriores dessa plataforma. Nesse último caso, o aplicativo falhará em tempo de execução quando tentar usar APIs inexistentes nas versões anteriores.

Testar usando APIs de nível superior

Depois de compilar o aplicativo, não deixe de testá-lo na plataforma especificada no atributo android:minSdkVersion do aplicativo. Para isso, crie um AVD que use a versão de plataforma exigida pelo aplicativo. Além disso, para assegurar compatibilidade com versões futuras, você deve executar e testar o aplicativo em todas as plataformas que usam um nível de API superior ao usado pelo aplicativo.

O Android SDK contém várias versões de plataforma que você pode usar, inclusive a versão mais recente, e fornece uma ferramenta de atualização que pode ser usada para baixar outras versões da plataforma, se necessário.

Para acessar o atualizador, use a ferramenta de linha de comando android, localizada no diretório <sdk>/tools. Você pode executar o atualizador de SDK executando android sdk. Você também pode simplesmente clicar duas vezes no arquivo android.bat (Windows) ou android (OS X/Linux).

Para executar o aplicativo em diferentes versões da plataforma no emulador, crie um AVD para cada versão de plataforma que será testada. Para obter mais informações sobre AVDs, consulte Criar e gerenciar dispositivos virtuais. Se você estiver usando um dispositivo físico para testes, verifique atentamente o nível de API da plataforma do Android onde os testes serão executados. Consulte a tabela na parte superior do documento para obter uma lista de versões de plataforma e seus níveis de API.

Filtrar a documentação de referência por nível de API

As páginas de documentação de referência no site de desenvolvedores Android oferecem um controle "Filter by API Level" no canto superior direito de cada página. Você pode usar o controle para mostrar a documentação apenas as partes da API que realmente podem ser acessadas pelo aplicativo, de acordo com o nível de API especificado no atributo android:minSdkVersion do arquivo de manifesto.

Para usar a filtragem, marque a caixa de seleção para ativá-la, logo abaixo da caixa de pesquisa da página. Em seguida, defina o controle "Filter by API Level" como o mesmo nível de API especificado pelo aplicativo. Note que as APIs introduzidas em níveis posteriores de API estarão esmaecidas e seu conteúdo estará oculto, pois não poderão ser acessadas pelo aplicativo.

A filtragem por nível de API na documentação não oferece uma exibição do que é novo ou foi introduzido em cada nível de API — ela simplesmente oferece uma forma de exibir toda a API associada a um determinado nível de API, excluindo elementos de API introduzidos em níveis de API posteriores.

Se você decidir que não quer filtrar a documentação da API, basta desativar o recurso usando a caixa de seleção. Por padrão, a filtragem de nível de API é desativada para que você possa ver toda a API da estrutura de trabalho, independentemente do nível de API.

Observe também que a documentação de referência de elementos de API individuais especifica o nível de API onde cada elemento foi introduzido. O nível de API para pacotes e classes é especificado como "Since <nível de API>" no canto superior direito da área de conteúdo, em cada página de documentação. O nível de API para membros de classe é especificado nos cabeçalhos de descrição detalhada, na margem direita.