<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 de API. O nível da API expresso por um aplicativo é comparado ao nível da API de determinado sistema Android, que pode variar entre diferentes dispositivos Android.

Apesar do nome, esse elemento é usado para especificar o nível da API, 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 das versões principais e secundárias.

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

atributos:

android:minSdkVersion

É um inteiro que designa o nível mínimo de API necessário para a execução do aplicativo. O sistema Android impede 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, e você não declarou o minSdkVersion adequado, quando instalado em um sistema com um nível de API incompatível, o aplicativo falha durante a execução ao tentar acessar as APIs indisponíveis. 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 de compatibilidade para manter a compatibilidade do aplicativo com versões futuras na versão direcionada. O aplicativo ainda pode 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 app, o sistema poderá ativar comportamentos de compatibilidade para garantir que o app 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, definir esse valor como "11" ou mais recente permite que o sistema aplique o tema padrão Holo ao app quando ele é executado no Android 3.0 ou mais recente e também desativa o modo de compatibilidade de tela quando ele é executado em telas maiores, porque o suporte ao nível 11 da API é implicitamente compatível com 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 de API mais recente e execute 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 (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 (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.

Aviso:não recomendamos declarar esse 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 dos usuários após uma atualização do sistema para uma API de nível mais alto. 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

Algumas versões do Android (além 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 é 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 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 apenas 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 chamado nível da 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 a seguir 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 o painel de distribuição.

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 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 de nível de API internamente, no próprio sistema Android.

Os aplicativos podem usar um elemento de manifesto fornecido pela API do 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: o nível mínimo de 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 ser restrito ao uso exclusivo daqueles definidos para o nível mínimo da API.
• android:maxSdkVersion: o nível de API máximo 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 mínimo de API do sistema exigido para a execução do aplicativo, o manifesto precisa incluir 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 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 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 descrição desse atributo para saber mais 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 de API em android:minSdkVersion é informar ao sistema Android que ele usa APIs que foram introduzidas no nível especificado.

Se o aplicativo for instalado de alguma forma em uma plataforma com um nível de API anterior, ele falhará no momento da 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 de 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 a seguir 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 da biblioteca 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 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 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 usada 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 executadas na nova plataforma e também quando executadas em versões posteriores da plataforma, conforme especificado pelo nível da API. No entanto, como versões anteriores da plataforma não incluem as novas APIs, os aplicativos que as usam 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 da 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. Depois de determinar a menor versão, crie um AVD usando a versão de plataforma e o nível de API correspondentes e teste completamente o 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 do 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 só possam instalar o aplicativo se os dispositivos estiverem executando uma versão compatível da plataforma Android. Isso ajuda a garantir que o aplicativo funcione corretamente nos dispositivos.

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

Testar usando níveis de API mais altos

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 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 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 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 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 de 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 o nível de API especificado pelo aplicativo no menu. As APIs introduzidas em um nível posterior de API vão estar esmaecidas, e o conteúdo delas vai estar oculto, já que elas não vão poder ser acessadas pelo aplicativo.

A filtragem por nível de API na documentação não mostra o que é novo ou foi introduzido em cada nível da API. Ele oferece uma maneira de mostrar toda a API associada a um determinado nível da API, excluindo elementos introduzidos em níveis mais recentes.

Para voltar a visualizar a documentação completa, selecione REL na parte de cima do menu de nível da API. 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.

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 "Adicionado 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.