<uses-sdk>

O Google Play usa os atributos de <uses-sdk> declarados no manifesto do aplicativo para filtrá-lo de dispositivos que não cumprem os requisitos de versão da plataforma. Antes de definir esses atributos, é necessário compreender os filtros do Google Play.

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 Controle de versão 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 direcionamento do aplicativo. 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 funcionando 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 (já que 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 a execução do aplicativo.

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 revalidá-lo 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á 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" no próprio manifesto é publicado no Google Play. Um usuário com dispositivo executando Android 1.6 (API de nível 4) faz o download 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, já que 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 elas 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 somente 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 Over the Air (OTA). Portanto, você deve considerar esse efeito no aplicativo antes de definir o atributo.

Introduzido na: API de nível 4

Versões futuras do Android (posteriores ao Android 2.0.1) não verificarão nem 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 download.
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 biblioteca oferecida por uma versão da plataforma Android.

A plataforma Android oferece uma API da biblioteca que pode ser usada pelos aplicativos para interagir com o sistema Android subjacente. A API da biblioteca 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 incluídas no sistema

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

As atualizações da API da biblioteca são projetadas de forma a manter a compatibilidade da nova API com as 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 somente para garantir a robustez da API e a segurança do aplicativo ou sistema. Todas as outras partes da API de revisões anteriores são propagadas sem modificação.

A API da biblioteca 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 os 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 saber 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 Q Beta 29 Q Destaques da plataforma
Android 9 28 P Destaques da plataforma
Android 8.1 27 O_MR1 Destaques da plataforma
Android 8.0 26 O Destaques da plataforma
Android 7.1.1
Android 7.1
25 N_MR1 Destaques da plataforma
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 biblioteca da API compatível.
  • Permite que os aplicativos descrevam a revisão de API da biblioteca exigida.
  • Permite que o sistema impeça a instalação de aplicativos com versões incompatíveis no dispositivo do usuário.

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

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

  • android:minSdkVersion — Especifica o nível de API mínimo em que o aplicativo pode ser executado. O valor padrão é “1”.
  • android:targetSdkVersion — Especifica o nível da API em que 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 direcionada, em vez de estar restrito ao uso exclusivo daqueles definidos para o nível mínimo da API.
  • android:maxSdkVersion — Especifica o nível de API máximo em que 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 do 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 próprio nível de API interno. O sistema somente permitirá o início da instalação se estas condições forem respeitadas:

  • Se um atributo android:minSdkVersion for declarado, o valor dele 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 que o inteiro de nível de API do sistema. Se não declarado, o sistema assumirá que o aplicativo não possui um nível máximo de API. Leia a documentação de <uses-sdk> para saber mais 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 ao sistema Android que usa APIs que foram introduzidas no nível especificado. Se o aplicativo fosse instalado de alguma forma em uma plataforma com um nível de API inferior, ele falharia no tempo de execução quando tentasse acessar APIs que não existem. O sistema impede tal resultado não permitindo que o aplicativo seja instalado se o nível de API mais baixo necessário for maior do que o da versão da plataforma no dispositivo direcionado.

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 saber mais 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 biblioteca 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 ajudar você a testar seu aplicativo em várias versões da plataforma Android, o SDK do Android inclui várias plataformas para download. Cada plataforma inclui uma imagem de sistema compatível que você pode executar em um AVD para testar seu 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 biblioteca, 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 em que você compilará o aplicativo. De forma geral, você deve compilar o aplicativo usando a menor versão de plataforma possível compatível com ele.

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 o 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 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. Nesse último caso, o aplicativo falhará no 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. 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 por ele.

O SDK do Android 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 fazer o download de 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 abrir o atualizador de SDK executando android sdk. Você também pode simplesmente clicar duas vezes no arquivo android.bat (Windows) ou android (SO 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 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 ver uma lista de versões de plataforma e os níveis de API correspondentes.

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 somente das 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 o filtro, marque a caixa de seleção para ativá-lo, 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. As APIs introduzidas em níveis posteriores de API estarão esmaecidas, e o conteúdo delas estará oculto, já que elas não poderão ser acessadas pelo aplicativo.

O filtro 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 — ele 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, o filtro de nível de API é desativado para que você possa ver toda a API da biblioteca, independentemente do nível de API.

A documentação de referência de elementos de API individuais especifica o nível de API em que 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.