<uses-sdk>

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 da API. O nível da API expresso por um aplicativo é 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 kit de desenvolvimento de software (SDK) 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.

Não é possível especificar que um app segmenta ou requer uma versão secundária do SDK.

Leia também o documento sobre controle de versões de aplicativos.

atributos:

android:minSdkVersion

É um inteiro designando o nível da API mínimo 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. Sempre declare esse atributo.

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 não for e você não tiver declarado o minSdkVersion adequado, quando instalado em um sistema com um nível da API incompatível, o aplicativo vai falhar durante o tempo de execução ao tentar acessar as APIs indisponíveis. Por esse motivo, não deixe de declarar o nível da API correto no atributo minSdkVersion.

android:targetSdkVersion

É um inteiro que indica o nível da 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 da API da plataforma for maior que a versão declarada na targetSdkVersion do aplicativo, o sistema vai poder ativar comportamentos de compatibilidade para que o aplicativo continue funcionando da maneira esperada. Você pode desativar esses comportamentos de compatibilidade especificando targetSdkVersion para corresponder ao nível da API da plataforma em que o aplicativo é executado.

Por exemplo, definir esse valor como "11" ou mais permite que o sistema aplique o tema padrão Holo ao app quando executado no Android 3.0 ou mais recente e também desative o modo de compatibilidade da tela em telas maiores, porque o suporte ao nível 11 da API oferece suporte implícito a 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, aumente o valor desse atributo para corresponder ao nível da API mais recente e execute um teste completo na versão da plataforma correspondente.

Introduzido no nível 4 da API

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 da 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 (nível 4 da API) 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 (nível 5 da API). 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 (nível 6 da API). Após a atualização, o sistema não consegue mais revalidar o aplicativo, porque o nível da 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.

Aviso: 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 funciona corretamente com novas versões, desde que use apenas APIs padrão e siga as práticas recomendadas de desenvolvimento. Segundo, 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 um nível da API mais recente. A maioria dos dispositivos em que o aplicativo provavelmente vai ser instalado recebe atualizações do sistema over the air (OTA) remotamente. Portanto, considere esse efeito no aplicativo antes de definir o atributo.

Introduzido no nível 4 da API

Algumas versões do Android (depois do Android 2.0.1) não verificam nem aplicam 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 em:

Nível 1 da API

O que é o nível da 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 são 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 da API. Cada versão da plataforma Android permite exatamente um nível da API, embora todos os níveis anteriores da API (até o nível 1) sejam implicitamente permitidos. A versão inicial da plataforma Android forneceu o nível 1 da API, e as versões subsequentes incrementaram esse nível. As APIs introduzidas ou descontinuadas em SDKs de pré-lançamento que não alcançaram a estabilidade da plataforma são marcadas como "API em desenvolvimento" em vez de um número de nível da API.

A tabela abaixo especifica o nível da 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 o painel de distribuição.

APIs em desenvolvimento

Na documentação de referência da API do Android, as APIs adicionadas ou descontinuadas em um SDK de pré-lançamento são marcadas com "API em desenvolvimento" em vez de um número de nível da API. Esse rótulo se aplica aos avisos "Adicionado em" e "Descontinuado em" até que o SDK alcance a estabilidade da plataforma e receba um nível de API principal ou secundário final. As APIs em desenvolvimento têm as seguintes características:

• Status de pré-lançamento: a adição ou descontinuação da API faz parte de uma versão de pré-lançamento ativa do SDK Beta ou Canary antes da finalização do nível da API.
• Sem garantia de estabilidade: ao contrário das APIs lançadas, que têm um nível da API permanente e são compatíveis com versões anteriores, as APIs em desenvolvimento podem ter as assinaturas alteradas, ser renomeadas ou ser totalmente removidas entre as versões de pré-lançamento do SDK.

Verificar se há APIs em desenvolvimento no momento da execução (PREVIEW_SDK_INT)

Como as APIs em desenvolvimento podem mudar ou desaparecer entre as versões de pré-lançamento, nunca use uma verificação de maior ou igual a (>=) para proteger chamadas para APIs não lançadas. Uma API presente na prévia 1 pode ser modificada ou descartada na prévia 2.

Em vez disso, os apps que testam recursos em fase de pré-lançamento precisam verificar o valor de Build.VERSION.PREVIEW_SDK_INT para igualdade estrita (==) em relação à revisão exata do pré-lançamento com que o app foi compilado:

• Nas versões finais de produção, Build.VERSION.PREVIEW_SDK_INT é sempre 0.
• Nas versões de pré-lançamento, PREVIEW_SDK_INT é exclusivo para cada versão.

Usos de nível da API no Android

O identificador de nível da 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 da 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 do nível da API em que podem ser executados, bem como o nível da API preferencial para que foram projetados. O elemento oferece três atributos principais:

• android:minSdkVersion: o nível mínimo da API em que o aplicativo pode ser executado. O valor padrão é "1".
• android:targetSdkVersion: 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 de destino, em vez de estar restrito ao uso exclusivo daqueles definidos para o nível mínimo da API.
• android:maxSdkVersion: o nível máximo da API em que o aplicativo pode ser executado. Importante: leia as informações sobre esse atributo nesta página antes de usá-lo.

Por exemplo, para especificar o nível da API mínimo 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 da 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 da 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 ser menor ou igual ao inteiro de nível da API do sistema. Se não for declarado, o sistema vai assumir que o aplicativo requer o nível da API 1.
• Se um atributo android:maxSdkVersion for declarado, o valor dele vai ser igual ou maior que o inteiro de nível da API do sistema. Se não for declarado, o sistema vai assumir que o aplicativo não tem um nível da API máximo. Leia a descrição desse atributo para mais informações sobre como o sistema o processa.

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 da API usando android:minSdkVersion é informar ao sistema Android que ele usa APIs que foram introduzidas no nível da API especificado.

Se o aplicativo for instalado de alguma forma em uma plataforma com um nível da API anterior, ele vai falhar no tempo de execução quando tentar acessar APIs que não existem. O sistema impede esse resultado não permitindo que o aplicativo seja instalado se o nível da API mais baixo necessário for maior que o da versão da plataforma no dispositivo de destino.

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 app 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 pode 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.

Mudanças abaixo da API, como as no próprio sistema, podem afetar o aplicativo quando executado no novo ambiente. É 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 apps 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 quando executados em versões futuras da plataforma, conforme a especificação do nível da API. No entanto, como as 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 da API

Ao desenvolver o aplicativo, você escolhe a versão da plataforma em que vai compilar o aplicativo. De forma geral, compile 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, crie um AVD usando a versão de plataforma e o nível da 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 da API da versão da plataforma.

Declarar um nível da API mínimo

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 da API da versão mais recente da plataforma. 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 ajuda a garantir 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 níveis da API superiores

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 verificar a compatibilidade com versões futuras, execute e teste o aplicativo em todas as plataformas que usam um nível da 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 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 da API da plataforma Android onde os testes são executados. Consulte a tabela neste 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 da API

As páginas de documentação de referência da plataforma Android oferecem um controle "nível da API" 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 a filtragem, selecione no menu o nível da 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 da 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 associadas a um determinado nível da API e excluir elementos introduzidos em níveis mais recentes.

Para voltar a ver a documentação completa, selecione REL na parte de cima do menu de nível da API. Por padrão, a filtragem por nível da API é desativada para que você possa ver toda a API de framework, não importa o nível da API.

A documentação de referência de elementos de API individuais especifica o nível da API em que cada elemento é introduzido ou descontinuado. O nível da API para pacotes e classes é especificado como "Adicionado no nível da API" e, quando aplicável, "Descontinuado no nível da API" no canto superior direito 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. Para adições ou descontinuações de APIs de pré-lançamento que não alcançaram a estabilidade da plataforma, esses locais mostram API em desenvolvimento em vez de um número de nível da API.