O Google Play usa os atributos <uses-sdk>
declarados no manifesto do app para filtrá-lo de dispositivos
que não atendem aos 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, 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. Não é possível derivar o nível da API usando o número de versão do Android associado. Por exemplo, ela não é igual à versão principal ou à soma das versões principal e secundária.
Leia também o documento sobre controle de versões de aplicativos.
- atributos:
-
android:minSdkVersion- Um número inteiro designando o nível mínimo de API necessário para a execução do aplicativo. O sistema Android vai impedir que o usuário instale
o aplicativo se o nível da API do sistema for menor que o valor especificado
nesse atributo. Sempre declare esse atributo.
Atenção:se você não declarar esse atributo, o sistema vai assumir o valor padrão de "1", o que indica que o aplicativo é compatível com todas as versões do Android. Se não for e você não tiver declarado a
minSdkVersionadequada, quando instalado em um sistema com um nível de API incompatível, o aplicativo falhará durante a execução ao tentar acessar as APIs indisponíveis. Por esse motivo, não deixe de declarar o nível adequado da API no atributominSdkVersion. android:targetSdkVersion- Um número inteiro que indica o nível da API de destino do aplicativo. Se não for definido, o valor padrão é o mesmo determinado em
minSdkVersion.Esse atributo informa ao sistema que você testou a versão de destino e o sistema não ativa nenhum comportamento de compatibilidade para manter a compatibilidade do app com versões futuras na versão de destino. 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 da API da plataforma for maior que a versão declarada pela
targetSdkVersiondo app, o sistema poderá ativar comportamentos de compatibilidade para que o app continue funcionando da maneira esperada. Você pode desativar esses comportamentos especificando umatargetSdkVersioncorrespondente 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 executado no Android 3.0 ou mais recente e também desativa o modo de compatibilidade da tela em telas maiores, já que o nível 11 da API é implicitamente compatível com telas maiores.
Há muitos comportamentos de compatibilidade que o sistema pode ativar com base no 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 mais recente da API e, em seguida, faça um teste completo do aplicativo na versão da plataforma correspondente.
Introduzido no: API de nível 4
- Um número 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. Em ambos os casos, se o atributo
maxSdkVersiondo aplicativo for menor que o nível da API usado pelo próprio sistema, ele não vai permitir que o aplicativo seja instalado. 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. Um usuário com um dispositivo que executa 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 OTA do sistema para o Android 2.0 (API de nível 5). Após a instalação da atualização, o sistema confere omaxSdkVersiondo 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 pode mais revalidar o aplicativo, porque o nível da API do sistema (6) agora é maior que o máximo aceito 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 seu 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 um nível de API mais recente. A maioria dos dispositivos em que o aplicativo provavelmente será instalado recebe atualizações over the air (OTA) periódicas do sistema. Portanto, considere o efeito delas no aplicativo antes de definir esse atributo.
Introduzido no: API de nível 4
Algumas versões do Android (além do Android 2.0.1) não verificam nem aplicam o atributomaxSdkVersiondurante a instalação ou revalidação. No entanto, o Google Play continua usando o atributo como filtro ao apresentar aos usuários aplicativos disponíveis para download.
- introduzido no:
- Nível 1 da API
O que é o nível da API?
O nível da API é um valor inteiro que identifica exclusivamente a revisão da API do 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 incluir atualizações para a API do framework de aplicativo 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 obsoletas, mas não são removidas. Assim, os aplicativos atuais ainda podem usá-las.
Em um número muito pequeno de casos, partes da API são modificadas ou removidas, embora normalmente essas mudanças sejam necessárias apenas para dar suporte à robustez da API e à segurança do aplicativo ou sistema. Todas as outras partes da API de revisões anteriores são propagadas sem modificação.
A API do framework fornecida por uma plataforma Android é especificada por um identificador inteiro chamado nível da API. Cada versão da plataforma Android oferece suporte a exatamente um nível de API, embora todos os níveis anteriores de API (até o nível 1) sejam implicitamente aceitos. A versão inicial da plataforma Android forneceu o nível 1 da API, e as versões subsequentes incrementaram esse nível.
A tabela abaixo especifica o nível da API com suporte em cada versão da plataforma Android. Para informações sobre os números relativos de dispositivos que executam cada versão, consulte o Painel de distribuição.
Usos do nível da API no Android
O identificador de nível de API desempenha um papel fundamental para ajudar a 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 compatível.
- Permite que os aplicativos descrevam a revisão da API do framework necessária.
- Ele permite que o sistema negocie a instalação de aplicativos no dispositivo do usuário para que aplicativos com versões incompatíveis não sejam instalados.
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
de framework (<uses-sdk>) para descrever os níveis mínimo e máximo
da 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 ser executado. Em alguns casos, isso permite que o aplicativo use elementos de manifesto ou comportamentos definidos no nível da API de destino, em vez de ficar restrito a usar apenas aqueles 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 que um aplicativo
exige para ser executado, o aplicativo inclui no manifesto 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 tenta instalar um aplicativo ou ao revalidar um
aplicativo após uma atualização do sistema, o sistema Android primeiro verifica os
atributos <uses-sdk> no manifesto do aplicativo e
compara os valores com o próprio nível interno da API. O sistema só permitirá o
início da instalação se estas condições forem atendidas:
- Se um atributo
android:minSdkVersionfor declarado, o valor será menor ou igual ao número inteiro de nível da API do sistema. Se não for declarado, o sistema vai presumir que o aplicativo exige o nível 1 da API. - Se um atributo
android:maxSdkVersionfor declarado, o valor dele será igual ou maior que o número inteiro de nível da API do sistema. Se não for declarado, o sistema vai presumir que o aplicativo não tem um nível máximo de API. Leia a descrição desse atributo para mais informações sobre como ele é processado pelo sistema.
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 principal motivo para um aplicativo declarar 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 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 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 fornecem 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 quase todas as mudanças na API do framework são aditivas, um aplicativo Android desenvolvido usando qualquer versão da API, conforme especificado pelo nível da API, é compatível com versões mais recentes da plataforma Android e níveis superiores de API. O aplicativo pode ser executado em todas as versões mais recentes 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 Android recebem atualizações do sistema over the air (OTA). O usuário pode instalar seu aplicativo, usá-lo com sucesso e, em seguida, receber uma atualização OTA para uma nova versão da plataforma Android. Depois que a atualização é instalada, seu aplicativo é executado em uma nova versão de ambiente de execução do ambiente, mas que ainda tem os recursos de API e sistema necessários para o aplicativo.
As mudanças abaixo da API, como as no próprio sistema, podem afetar seu aplicativo quando ele é executado no novo ambiente. É importante que você, como desenvolvedor de aplicativos, entenda a aparência e o comportamento do aplicativo em cada 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 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 executados na nova plataforma e também quando executados em versões posteriores da plataforma, conforme especificado pelo nível da API. No entanto, como as versões anteriores da plataforma não incluem as novas APIs, os aplicativos que usam as novas APIs não podem ser executados nessas plataformas.
Embora não seja provável que um dispositivo Android faça downgrade para uma versão anterior da plataforma, é importante notar que pode haver muitos dispositivos executados em 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.
Selecione uma versão de plataforma e um nível de API
Ao desenvolver o aplicativo, escolha a versão da plataforma em que você vai compilar o aplicativo. Em geral, compile seu aplicativo usando a menor versão possível da plataforma 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 da plataforma
e o nível da API correspondentes e teste totalmente seu aplicativo. Declare um
atributo android:minSdkVersion no manifesto do aplicativo e
defina o valor dele como o nível da 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 mais recente da plataforma, defina o
atributo android:minSdkVersion como o nível da API dessa
versão mais recente. Dessa forma, os usuários só poderão instalar seu
aplicativo se os dispositivos deles estiverem executando uma versão compatível da plataforma
Android. Por sua vez, isso ajuda a garantir que seu aplicativo possa funcionar corretamente nos
dispositivos.
Se o aplicativo usar APIs introduzidas na versão mais recente da 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. No último
caso, o aplicativo falha durante a execução ao tentar usar APIs que não
existem nas versões anteriores.
Testar em níveis mais altos da API
Depois de compilar seu aplicativo, teste-o 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 pelo aplicativo.
O SDK do Android inclui várias versões da plataforma que você pode usar, incluindo a versão mais recente, e oferece uma ferramenta de atualização que pode ser usada para fazer o download de outras versões da plataforma, conforme 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. Também é possível
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 saber mais sobre AVDs, consulte Criar e gerenciar dispositivos virtuais. Se você estiver usando um dispositivo físico para testes, verifique se você sabe o nível da API da plataforma Android em que ele é executado. Consulte na tabela deste documento uma lista de versões de plataforma e os respectivos 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 da Plataforma Android oferecem um
controle de "nível da API" no canto superior esquerdo de cada página. Você pode usar o
controle para mostrar a documentação apenas de partes da API que realmente
podem ser acessadas pelo aplicativo, com base no nível da API especificado no
atributo android:minSdkVersion do arquivo de manifesto.
Para usar a filtragem, selecione o nível da API especificado pelo aplicativo no menu. As APIs introduzidas em um nível posterior da API ficam esmaecidas, e o conteúdo delas fica oculto, já que não podem ser acessadas pelo aplicativo.
A filtragem por nível de API na documentação não mostra o que há de novo ou o que foi introduzido em cada nível da API. Ele oferece uma maneira de visualizar toda a API associada a um determinado nível, excluindo elementos da API introduzidos em níveis posteriores.
Para voltar a visualizar a documentação completa, selecione REL na parte superior do menu do nível da API. Por padrão, a filtragem no nível da API está desativada para que você possa visualizar a API completa do framework, independente do nível da API.
A documentação de referência de elementos individuais da API especifica o nível da API em que cada elemento é 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 de documentação. O nível da API para membros de classe é especificado nos cabeçalhos de descrição detalhada, na margem direita.