O Google Play usa os atributos <uses-sdk> declarados no manifesto do app para fazer um filtro que mostre seu app em dispositivos que não cumprem os requisitos de versão da plataforma. Antes de definir esses atributos, é necessário entender 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 usando 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 Controlar a 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 vai 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 vai 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 no nível 3 da API) e você não declarou a minSdkVersion correta, o aplicativo vai falhar durante a execução quando tentar acessar APIs não disponíveis se instalado em sistemas com um nível de API anterior 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 for definido, o valor padrão é o mesmo determinado 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 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 vai poder ativar comportamentos de compatibilidade para garantir que o aplicativo continue funcionando da maneira esperada. Você pode desativar esses comportamentos especificando uma targetSdkVersion correspondente ao nível de API da plataforma em que 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 versões mais recentes e desative o modo de compatibilidade de tela quando executado em telas maiores (já que a API de nível 11 oferece suporte implicitamente para telas maiores).

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

Para manter o aplicativo junto com cada versão do Android, você precisa aumentar o valor desse atributo para corresponder ao nível da API mais recente e executar um teste completo na versão da 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 confere o valor desse atributo ao instalar e revalidar um 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, a instalação do aplicativo não será permitida. Se há uma revalidação depois de uma atualização do sistema, o aplicativo é 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. O usuário que tem um dispositivo com o Android 1.6 (API de nível 4) faz o download e instala o app. Depois de algumas semanas, o usuário recebe uma atualização remota do sistema para o Android 2.0 (API de nível 5). Após a instalação da atualização, o sistema confere o maxSdkVersion do aplicativo e faz a revalidação. 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, porque 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, e é removido do dispositivo.

Atenção: não recomendamos a declaração desse atributo. Primeiro, não é necessário 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 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 mais recente. A maioria dos dispositivos em que o aplicativo provavelmente vai ser instalado recebe atualizações over the air (OTA) remotamente. Portanto, você precisa considerar esse efeito no aplicativo antes de definir o atributo.

Introduzido na API de nível 4

As versões futuras do Android (depois do Android 2.0.1) não vão mais verificar nem aplicar o atributo maxSdkVersion durante a instalação ou revalidação. No entanto, o Google Play vai continuar usando 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 de framework oferecida por uma versão da plataforma Android.

A plataforma Android oferece uma API de framework que pode ser usada pelos aplicativos para interagir com o sistema Android. A API de framework 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 do framework de aplicativos Android que fornece.

As atualizações da API de framework 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 descontinuadas, mas não são removidas, permitindo que continuem sendo usadas pelos aplicativos existentes. 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 de framework oferecida 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 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.

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 da API de framework para a qual oferece suporte.
• Permite que os aplicativos descrevam a revisão de API de framework 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 do nível de API internamente, no próprio sistema Android.

Os aplicativos podem usar um elemento de manifesto fornecido pela API de framework (<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 de 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 precisa conter um elemento <uses-sdk> com um atributo android:minSdkVersion. O valor de android:minSdkVersion é o número inteiro correspondente ao nível de API da versão mais antiga da plataforma Android em que 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 vai conferir primeiro os atributos <uses-sdk> no manifesto do aplicativo e comparar os valores com o próprio nível de API interno. O sistema só vai permitir o início da instalação se estas condições forem respeitadas:

• Se um atributo android:minSdkVersion for declarado, o valor dele vai precisar ser menor ou igual ao inteiro de nível de API do sistema. Se não for declarado, o sistema vai assumir que o aplicativo mostra a API de nível 1.
• Se um atributo android:maxSdkVersion for declarado, o valor vai precisar ser igual ou maior que o inteiro de nível de API do sistema. Se não for declarado, o sistema vai assumir que o aplicativo não tem 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 ele 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 anterior, ele falharia no momento da execução quando tentasse acessar APIs que não existem. O sistema impede esse resultado não permitindo que o aplicativo seja instalado se o nível de API mais baixo necessário for maior 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, ele vai precisar declarar um atributo android:minSdkVersion com o valor de "3". Em seguida, o aplicativo vai poder ser instalado em plataformas como o Android 1.5 (nível 3 da API) e Android 1.6 (nível 4 da API), mas não nas plataformas Android 1.1 (nível 2 da API) e Android 1.0 (nível 1 da API).

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 da API que você precisa 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 de framework são incrementais, um aplicativo Android desenvolvido usando qualquer versão da API (conforme especificado pelo nível de API) é compatível com versões futuras da plataforma Android e níveis de API mais recentes. O aplicativo precisa ser executado em todas as versões futuras da plataforma Android, exceto em casos isolados em que o aplicativo usa uma parte da API que é removida mais tarde por algum motivo.

A compatibilidade com versões futuras é importante porque muitos dispositivos Android recebem atualizações do sistema over the air (OTA). O usuário pode instalar e usar o aplicativo de forma bem-sucedida e receber mais tarde uma atualização OTA para uma nova versão da plataforma Android. Após a instalação da atualização, o aplicativo é executado em uma nova versão de execução do ambiente. No entanto, essa versão tem os recursos de API e sistema necessários para o aplicativo.

Em alguns casos, mudanças abaixo da API, como as no próprio sistema, podem afetar o aplicativo quando executado no novo ambiente. Por esse motivo, é importante que você, como desenvolvedor do aplicativo, entenda qual vai 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 framework, 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 futuras 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 as usam não podem ser executados nessas plataformas.

Embora seja pouco provável que um dispositivo Android faça downgrade para uma versão anterior da plataforma, é importante notar que podem existir muitos dispositivos executando versões anteriores. 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, é preciso escolher a versão da plataforma em que você vai compilar o aplicativo. De forma geral, você precisa compilar o aplicativo usando a menor versão da plataforma possível a que ele oferece suporte.

Você pode determinar a menor versão da plataforma possível compilando o aplicativo para builds sucessivamente menores. Após determinar a menor versão, você precisa criar um AVD usando a versão de plataforma e nível de API correspondentes, além de 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. Isso garante que os usuários possam instalar o aplicativo apenas se os dispositivos tiverem uma versão compatível da plataforma Android. Por outro lado, isso garante que o aplicativo funcione adequadamente nos dispositivos deles.

Se o aplicativo usa APIs introduzidas na versão mais recente da plataforma, mas não declara um atributo android:minSdkVersion, ele vai 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 falha na execução ao tentar usar APIs que não existem nas versões anteriores.

Testar usando APIs de nível superior

Após compilar o aplicativo, faça um teste na plataforma especificada no atributo android:minSdkVersion. Para isso, crie um AVD que use a versão da plataforma exigida pelo aplicativo. Além disso, para assegurar compatibilidade com versões futuras, você precisa executar e testar o aplicativo em todas as plataformas que usam um nível de API mais recente do que o usado por ele.

O SDK do Android contém várias versões da plataforma que você pode usar, incluindo 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. É possível abrir o atualizador do 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 da plataforma que vai ser testada. Para mais informações sobre AVDs, consulte Criar e gerenciar dispositivos virtuais. Se você está usando um dispositivo físico para testes, confirme atentamente o nível de API da plataforma Android onde os testes são executados. Consulte a tabela no início deste documento para ver uma lista de versões da 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 da Plataforma Android oferecem um controle "API Level" na parte de cima à esquerda de cada página. Você pode usar o controle para mostrar a documentação apenas para as partes da API que realmente podem ser acessadas pelo aplicativo, de acordo com o nível da API especificado no atributo android:minSdkVersion do arquivo de manifesto.

Para usar o filtro, marque a caixa de seleção para ativar, 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 futuros vão estar esmaecidas, e o conteúdo delas vai estar oculto, já que elas não vão poder ser acessadas pelo aplicativo.

Filtrar por nível de API na documentação não mostra o que é novo ou foi introduzido em cada nível da API. Isso é apenas uma forma de mostrar todas as APIs associada a um determinado nível da API e excluí elementos introduzidos em níveis mais recentes.

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 de framework, não importa o 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 da API para pacotes e classes é especificado como "Since <nível de API>" no canto de cima à direita da área de conteúdo em cada página da documentação. O nível da API para membros de classe é especificado nos cabeçalhos de descrição detalhada, na margem direita.