<uses-sdk>

O Google Play usa os atributos <uses-sdk> declarados no manifesto para filtrar o app dos dispositivos que não atendem aos requisitos da 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 app é comparado ao de um 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 único. Não é possível derivar o nível da API do número de versão do Android associado. Por exemplo, não é o mesmo que a versão principal ou a soma das versões principal e secundária.

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

atributos:
android:minSdkVersion
Um número inteiro que designa 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.

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

android:targetSdkVersion
Um número inteiro que indica o nível da API para o qual o aplicativo é direcionado. Se não for definido, o valor padrão é o mesmo determinado em minSdkVersion.

Esse atributo informa ao sistema que o app foi testado na versão de destino. O sistema não ativa nenhum comportamento para manter a compatibilidade do app com versões futuras da 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 pelo targetSdkVersion do app, o sistema poderá ativar comportamentos de compatibilidade para 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 executado no Android 3.0 ou versões mais recentes, além de desativar o modo de compatibilidade da tela quando executado em telas maiores, porque o suporte à API de nível 11 é 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 a cada versão do Android, aumente o valor desse atributo para que corresponda ao nível da API mais recente e faça um teste completo do aplicativo na versão de plataforma correspondente.

Introduzido no: nível 4 da API

android:maxSdkVersion
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 maxSdkVersion do aplicativo for menor que o nível de API usado pelo próprio sistema, o sistema não vai permitir a instalação do aplicativo. 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 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 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 poderá mais revalidar o aplicativo, porque o nível de 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 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 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 em 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 vai ser instalado recebe atualizações over the air (OTA) periódicas do sistema. Considere o efeito delas no aplicativo antes de definir o atributo.

Introduzido no: nível 4 da API

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 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 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 incluir atualizações para a API do framework de aplicativos Android fornecida.

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 recebem upgrade, as partes substituídas são descontinuadas, 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. Normalmente, essas mudanças são necessárias apenas para oferecer suporte à robustez da API e à segurança de aplicativos ou sistema. Todas as outras partes da API de revisões anteriores são propagadas sem modificação.

A API de framework fornecida por uma plataforma Android é especificada por um identificador inteiro denominado nível da API. Cada versão da plataforma Android oferece suporte a exatamente um nível de API, embora o suporte seja implícito para todos os níveis anteriores da API (até o nível 1 da API). 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 a seguir especifica o nível de 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.

Versão da plataformaNível da APIVERSION_CODEObservações
Android 15 API 34 → DP2 VANILLA_ICE_CREAM Destaques da plataforma
Android 14 34 UPSIDE_DOWN_CAKE Destaques da plataforma
Android 13 33 TIRAMISU Destaques da plataforma
Android 12 32 S_V2 Destaques da plataforma
31 S Destaques da plataforma
Android 11 30 R Destaques da plataforma
Android 10 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 fundamental para ajudar a garantir a melhor experiência possível para usuários e desenvolvedores de aplicativos:

  • Ele permite que a plataforma Android descreva a revisão máxima de API de framework que ela aceita.
  • Ele permite que os aplicativos descrevam a revisão de API do framework exigida.
  • Ele permite que o sistema negocie a instalação de aplicativos no dispositivo do usuário para que não sejam instalados aplicativos incompatíveis com versões.

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 eles podem ser executados, bem como o nível preferido da API para o qual 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 para o qual o aplicativo foi projetado. 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 ficar restrito ao uso apenas daqueles definidos para o nível mínimo da API.
  • android:maxSdkVersion: o nível máximo de 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 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 de API da versão mais antiga da plataforma Android em que o aplicativo pode ser executado.

Quando o usuário tenta instalar um app ou ao revalidá-lo após uma atualização do sistema, o sistema Android verifica primeiro os atributos <uses-sdk> no manifesto do app e compara os valores com o próprio nível interno da API. O sistema só vai permitir o início da instalação se estas condições forem atendidas:

  • Se um atributo android:minSdkVersion for declarado, o valor dele será menor ou igual ao número inteiro do nível da API do sistema. Se não for declarado, o sistema entenderá que o aplicativo exige o nível 1 da API.
  • Se um atributo android:maxSdkVersion for 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 entenderá 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 o sistema processa isso.

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 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 app for instalado em uma plataforma com um nível de API menor, ele falhará durante a execução quando tentar acessar APIs que não existem. O sistema evita 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 de 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 de API mais recentes. 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 e usar o aplicativo e, em seguida, receber uma atualização OTA para uma nova versão da plataforma Android. Depois que a atualização for instalada, o aplicativo será executado em uma nova versão do ambiente de execução do ambiente, mas que ainda tenha os recursos de API e sistema necessários para ele.

As mudanças abaixo da API, como as no próprio sistema, podem afetar seu aplicativo quando ele for executado no novo ambiente. É importante que você, como desenvolvedor de aplicativos, entenda a aparência e o comportamento do aplicativo em cada ambiente do 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 mais recentes 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 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.

Selecione uma versão da plataforma e um nível da API

Ao desenvolver o aplicativo, você escolhe a versão da plataforma em que o aplicativo vai ser compilado. Em geral, compile o 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 faça um teste completo do 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. Dessa forma, os usuários só poderão 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 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 quando tenta usar APIs que não existem nas versões anteriores.

Testar em níveis de API mais altos

Depois de 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 superior ao usado por ele.

O SDK do Android inclui várias versões de plataforma que podem ser usadas, 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 mais informações sobre AVDs, consulte Criar e gerenciar dispositivos virtuais. Se você estiver usando um dispositivo físico para testes, verifique o nível da API da plataforma Android em que ela é executada. Consulte a tabela neste documento para ver uma lista de versões da 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. Use o controle para mostrar a documentação somente das 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 no menu o nível da API especificado pelo aplicativo. As APIs introduzidas em níveis posteriores de API ficam esmaecidas e o conteúdo delas fica mascarado, 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 de API. Ela oferece uma maneira de visualizar toda a API associada a determinado nível de API, excluindo elementos introduzidos em níveis mais recentes.

Para voltar a visualizar a documentação completa, selecione REL na parte superior do menu de nível de API. Por padrão, a filtragem de nível de API está desativada para que você possa visualizar a API de framework completa, independentemente 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 da documentação. O nível de API para membros de classe é especificado nos cabeçalhos de descrição detalhada, na margem direita.