Noções básicas sobre níveis da API do Android

  • Artigo

O Xamarin.Android tem várias configurações de nível de API do Android que determinam a compatibilidade do aplicativo com várias versões do Android. Este guia explica o que essas configurações significam, como configurá-las e que efeito elas têm em seu aplicativo em tempo de execução.

Início rápido

O Xamarin.Android expõe três configurações de projeto de nível de API do Android:

  • Estrutura de Destino – especifica qual estrutura usar na criação do aplicativo. Esse nível de API é usado em tempo de compilação pelo Xamarin.Android.

  • Versão mínima do Android – especifica a versão mais antiga do Android que você deseja que seu aplicativo dê suporte. Esse nível de API é usado em tempo de execução pelo Android.

  • Versão de destino do Android – especifica a versão do Android na qual seu aplicativo se destina a ser executado. Esse nível de API é usado em tempo de execução pelo Android.

Antes de configurar um nível de API para seu projeto, você deve instalar os componentes da plataforma do SDK para esse nível de API. Para obter mais informações sobre como baixar e instalar componentes do SDK do Android, consulte Instalação do SDK do Android.

Observação

A partir de agosto de 2021, o Console do Google Play exige que novos aplicativos direcionem o nível 30 da API (Android 11.0) ou superior. Os aplicativos existentes são necessários para atingir o nível de API 30 ou superior a partir de novembro de 2021. Para obter mais informações, consulte Requisitos de nível de API de destino para o Play Console em "Criar e configurar seu aplicativo" na documentação do Play Console.

Normalmente, todos os três níveis de API Xamarin.Android são definidos com o mesmo valor. Na página Aplicativo , defina Compilar usando a versão do Android (Target Framework) para a versão mais recente da API estável (ou, no mínimo, para a versão do Android que tenha todos os recursos necessários). Na captura de tela a seguir, o Target Framework é definido como Android 7.1 (Nível de API 25 – Nougat):

A versão do Target Framework usa como padrão compilar usando a versão do Android

Na página Manifesto do Android , defina a versão mínima do Android para Usar Compilar usando a versão do SDK e defina a versão do Android de destino com o mesmo valor que a versão do Target Framework (na captura de tela a seguir, o Target Android Framework está definido como Android 7.1 (Nougat)):

Versões mínimas e de destino do Android definidas como a versão do Target Framework

Se você quiser manter a compatibilidade com versões anteriores do Android, defina a versão mínima do Android como destino para a versão mais antiga do Android que você deseja que seu aplicativo dê suporte. (Observe que o Nível 14 da API é o nível mínimo de API necessário para os serviços Google Play e o suporte do Firebase.) A configuração de exemplo a seguir dá suporte a versões do Android do Nível 14 da API até o nível 25 da API:

Compilar usando o nível de API 25 Nougat, versão mínima do Android definida como nível de API 14

Se o aplicativo der suporte a várias versões do Android, seu código deverá incluir verificações de runtime para garantir que seu aplicativo funcione com a configuração de versão mínima do Android (consulte Verificações de runtime para versões do Android abaixo para obter detalhes). Se você estiver consumindo ou criando uma biblioteca, consulte Níveis de API e Bibliotecas abaixo para obter práticas recomendadas na definição de configurações de nível de API para bibliotecas.

Versões do Android e níveis de API

À medida que a plataforma Android evolui e novas versões do Android são lançadas, cada versão do Android recebe um identificador inteiro exclusivo, chamado Nível de API. Portanto, cada versão do Android corresponde a um único nível de API do Android. Como os usuários instalam aplicativos em versões mais antigas e as versões mais recentes do Android, os aplicativos Android do mundo real devem ser projetados para funcionar com vários níveis de API do Android.

Versões do Android

Cada versão do Android tem vários nomes:

  • A versão do Android, como o Android 9.0
  • Um nome de código (ou sobremesa), como Pizza
  • Um nível de API correspondente, como o nível de API 28

Um nome de código do Android pode corresponder a várias versões e níveis de API (como visto na tabela abaixo), mas cada versão do Android corresponde exatamente a um nível de API.

Além disso, o Xamarin.Android define códigos de versão de build que são mapeados para os níveis de API do Android conhecidos no momento. A tabela a seguir pode ajudá-lo a traduzir entre o nível da API, a versão do Android, o nome do código e o código de versão de build do Xamarin.Android (os códigos de versão de build são definidos no Android.OS namespace):

Nome Versão Nível da API Liberado Criar código de versão
Q 10.0 29 Ago 2020 BuildVersionCodes.Q
Pie 9.0 28 Agosto de 2018 BuildVersionCodes.P
Oreo 8.1 27 Dez 2017 BuildVersionCodes.OMr1
Oreo 8.0 26 Ago 2017 BuildVersionCodes.O
Nougat 7.1 25 Dez 2016 BuildVersionCodes.NMr1
Nougat 7.0 24 Agosto de 2016 BuildVersionCodes.N
Marshmallow 6.0 23 Ago/2015 BuildVersionCodes.M
Lollipop 5.1 22 Mar 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 Nov 2014 BuildVersionCodes.Lollipop
Relógio Kitkat 4,4W 20 Jun 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 Out de 2013 BuildVersionCodes.KitKat
Jujuba 4.3 18 Julho de 2013 BuildVersionCodes.JellyBeanMr2
Jujuba 4.2-4.2.2 17 Novembro de 2012 BuildVersionCodes.JellyBeanMr1
Jujuba 4.1-4.1.1 16 Jun 2012 BuildVersionCodes.JellyBean
Sanduíche de Sorvete 4.0.3-4.0.4 15 Dez 2011 BuildVersionCodes.IceCreamSandwichMr1
Sanduíche de Sorvete 4.0-4.0.2 14 Out 2011 BuildVersionCodes.IceCreamSandwich
Colmeia 3.2 13 Jun 2011 BuildVersionCodes.HoneyCombMr2
Colmeia 3.1.x 12 Maio de 2011 BuildVersionCodes.HoneyCombMr1
Colmeia 3.0.x 11 Fevereiro de 2011 BuildVersionCodes.HoneyComb
Gingerbread 2.3.3-2.3.4 10 Fevereiro de 2011 BuildVersionCodes.GingerBreadMr1
Gingerbread 2.3-2.3.2 9 Novembro de 2010 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 Jun 2010 BuildVersionCodes.Froyo
Eclair 2.1.x 7 Janeiro de 2010 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 Dez de 2009 BuildVersionCodes.Eclair01
Eclair 2.0 5 Novembro de 2009 BuildVersionCodes.Eclair
Donut 1.6 4 Sep 2009 BuildVersionCodes.Donut
Cupcake 1.5 3 Maio de 2009 BuildVersionCodes.Cupcake
Base 1,1 2 Fevereiro de 2009 BuildVersionCodes.Base11
Base 1.0 1 Outubro de 2008 BuildVersionCodes.Base

Como esta tabela indica, novas versões do Android são lançadas com frequência – às vezes, mais de uma versão por ano. Como resultado, o universo de dispositivos Android que podem executar seu aplicativo inclui uma ampla variedade de versões mais antigas e mais recentes do Android. Como você pode garantir que seu aplicativo será executado de forma consistente e confiável em tantas versões diferentes do Android? Os níveis de API do Android podem ajudá-lo a gerenciar esse problema.

Níveis da API do Android

Cada dispositivo Android é executado em exatamente um nível de API – esse nível de API tem a garantia de ser exclusivo por versão da plataforma Android. O nível de API identifica com precisão a versão do conjunto de APIs para o qual seu aplicativo pode chamar; identifica a combinação de elementos de manifesto, permissões etc. que você codifica em como um desenvolvedor. O sistema de níveis de API do Android ajuda o Android a determinar se um aplicativo é compatível com uma imagem do sistema Android antes de instalar o aplicativo em um dispositivo.

Quando um aplicativo é criado, ele contém as seguintes informações de nível de API:

  • O nível de API de destino do Android no qual o aplicativo foi criado para ser executado.

  • O nível mínimo de API do Android que um dispositivo Android deve ter para executar seu aplicativo.

Essas configurações são usadas para garantir que a funcionalidade necessária para executar o aplicativo corretamente esteja disponível no dispositivo Android no momento da instalação. Caso contrário, o aplicativo será impedido de ser executado nesse dispositivo. Por exemplo, se o nível de API de um dispositivo Android for inferior ao nível mínimo de API que você especificar para seu aplicativo, o dispositivo Android impedirá que o usuário instale seu aplicativo.

Configurações de nível de API do Projeto

As seções a seguir explicam como usar o Gerenciador de SDK para preparar seu ambiente de desenvolvimento para os níveis de API que você deseja direcionar, seguido por explicações detalhadas de como definir as configurações de estrutura de destino, versão mínima do Android e versão de destino do Android no Xamarin.Android.

Plataformas do SDK do Android

Antes de selecionar um nível de API de Destino ou Mínimo no Xamarin.Android, você deve instalar a versão da plataforma SDK do Android que corresponde a esse nível de API. O intervalo de opções disponíveis para a Estrutura de Destino, a versão mínima do Android e a versão do Android de destino é limitada ao intervalo de versões do SDK do Android que você instalou. Você pode usar o Gerenciador de SDK para verificar se as versões necessárias do SDK do Android estão instaladas e pode usá-la para adicionar novos níveis de API necessários para seu aplicativo. Se você não estiver familiarizado com como instalar níveis de API, consulte Instalação do SDK do Android.

Estrutura de Destino

A Estrutura de Destino (também conhecida como compileSdkVersion) é a versão específica da estrutura do Android (nível de API) para a qual seu aplicativo é compilado no momento da compilação. Essa configuração especifica quais APIs seu aplicativo espera usar quando é executado, mas não tem efeito sobre quais APIs estão realmente disponíveis para seu aplicativo quando ele é instalado. Como resultado, alterar a configuração da Estrutura de Destino não altera o comportamento do runtime.

A Estrutura de Destino identifica em quais versões de biblioteca seu aplicativo está vinculado– essa configuração determina quais APIs você pode usar em seu aplicativo. Por exemplo, se você quiser usar o método NotificationBuilder.SetCategory introduzido no Android 5.0 Lollipop, defina a Estrutura de Destino como Nível de API 21 (Lollipop) ou posterior. Se você definir a Estrutura de Destino do projeto para um nível de API, como o Nível de API 19 (KitKat) e tentar chamar o SetCategory método em seu código, receberá um erro de compilação.

Recomendamos que você sempre compile com a versão mais recente do Target Framework disponível. Isso fornece mensagens de aviso úteis para todas as APIs preteridas que podem ser chamadas pelo seu código. O uso da versão mais recente da Estrutura de Destino é especialmente importante quando você usa as versões mais recentes da biblioteca de suporte. Cada biblioteca espera que seu aplicativo seja compilado no nível mínimo de API da biblioteca de suporte ou superior.

Para acessar a configuração estrutura de destino no Visual Studio, abra as propriedades do projeto no Gerenciador de Soluções e selecione a página Aplicativo:

Página de aplicativo das propriedades do projeto

Defina a Estrutura de Destino selecionando um nível de API no menu suspenso em Compilar usando a versão do Android , conforme mostrado acima.

Versão mínima do Android

A versão mínima do Android (também conhecida como minSdkVersion) é a versão mais antiga do sistema operacional Android (ou seja, o nível de API mais baixo) que pode instalar e executar seu aplicativo. Por padrão, um aplicativo só pode ser instalado em dispositivos que correspondam à configuração da Estrutura de Destino ou superior; se a configuração Versão mínima do Android for inferior à configuração da Estrutura de Destino, seu aplicativo também poderá ser executado em versões anteriores do Android. Por exemplo, se você definir a Estrutura de Destino como Android 7.1 (Nougat) e definir a versão Mínima do Android como Android 4.0.3 (Ice Cream Sandwich), seu aplicativo poderá ser instalado em qualquer plataforma do nível de API 15 para o nível de API 25, inclusive.

Embora seu aplicativo possa ser criado e instalado com êxito nesse intervalo de plataformas, isso não garante que ele será executado com êxito em todas essas plataformas. Por exemplo, se seu aplicativo estiver instalado no Android 5.0 (Lollipop) e seu código chamar uma API disponível apenas no Android 7.1 (Nougat) e mais recente, seu aplicativo receberá um erro de runtime e possivelmente falhará. Portanto, seu código deve garantir, em runtime, que ele chama apenas as APIs compatíveis com o dispositivo Android em que ele está sendo executado. Em outras palavras, seu código deve incluir verificações explícitas de runtime para garantir que seu aplicativo use APIs mais recentes somente em dispositivos recentes o suficiente para dar suporte a eles. Verificações de runtime para versões do Android, mais adiante neste guia, explica como adicionar essas verificações de runtime ao seu código.

Para acessar a configuração Versão mínima do Android no Visual Studio, abra as propriedades do projeto no Gerenciador de Soluções e selecione a página Manifesto do Android. No menu suspenso, em Versão mínima do Android , você pode selecionar a versão mínima do Android para seu aplicativo:

Opção mínima do Android para destino definida como Compilar usando a versão do SDK

Se você selecionar Usar Compilar usando a versão do SDK, a versão mínima do Android será igual à configuração estrutura de destino.

Versão do Android de destino

A versão do Android de destino (também conhecida como targetSdkVersion) é o nível de API do dispositivo Android em que o aplicativo espera ser executado. O Android usa essa configuração para determinar se deseja habilitar comportamentos de compatibilidade– isso garante que seu aplicativo continue funcionando da maneira esperada. O Android usa a configuração de versão do Android de destino do seu aplicativo para descobrir quais alterações de comportamento podem ser aplicadas ao seu aplicativo sem quebrá-lo (é assim que o Android fornece compatibilidade futura).

A Estrutura de Destino e a versão do Android de destino, embora tenham nomes muito semelhantes, não são a mesma coisa. A configuração estrutura de destino comunica informações de nível de API de destino para Xamarin.Android para uso em tempo de compilação, enquanto a versão do Android de destino comunica informações de nível de API de destino para o Android para uso em tempo de execução (quando o aplicativo está instalado e em execução em um dispositivo).

Para acessar essa configuração no Visual Studio, abra as propriedades do projeto no Gerenciador de Soluções e selecione a página Manifesto do Android. No menu suspenso em Versão de destino do Android , você pode selecionar a versão de Destino do Android para seu aplicativo:

Versão do Android de destino definida como Compilar usando a versão do SDK

Recomendamos que você defina explicitamente a versão de Destino do Android para a versão mais recente do Android que você usa para testar seu aplicativo. Idealmente, ele deve ser definido como a versão mais recente do SDK do Android– isso permite que você use novas APIs antes de trabalhar com as alterações de comportamento. Para a maioria dos desenvolvedores, não recomendamos definir a versão de Destino do Android para Usar Compilar usando a versão do SDK.

Em geral, a versão de destino do Android deve ser limitada pela Versão Mínima do Android e pela Estrutura de Destino. Ou seja:

Versão mínima do <Android = Versão de destino do <Android = Estrutura de Destino

Para obter mais informações sobre os níveis do SDK, consulte a documentação do SDK de usos do Desenvolvedor do Android.

Verificações de runtime para versões do Android

À medida que cada nova versão do Android é lançada, a API de estrutura é atualizada para fornecer funcionalidade nova ou de substituição. Com poucas exceções, a funcionalidade de API de versões anteriores do Android é levada adiante para versões mais recentes do Android sem modificações. Como resultado, se seu aplicativo for executado em um determinado nível de API do Android, ele normalmente poderá ser executado em um nível de API do Android posterior sem modificações. Mas e se você também quiser executar seu aplicativo em versões anteriores do Android?

Se você selecionar uma versão mínima do Android que seja inferior à configuração da Estrutura de Destino, algumas APIs poderão não estar disponíveis para seu aplicativo em runtime. No entanto, seu aplicativo ainda pode ser executado em um dispositivo anterior, mas com funcionalidade reduzida. Para cada API que não está disponível em plataformas Android correspondentes à sua configuração de versão mínima do Android, seu código deve marcar explicitamente o valor da Android.OS.Build.VERSION.SdkInt propriedade para determinar o nível de API da plataforma em que o aplicativo está sendo executado. Se o nível de API for inferior à versão mínima do Android que dá suporte à API que você deseja chamar, seu código precisará encontrar uma maneira de funcionar corretamente sem fazer essa chamada à API.

Por exemplo, vamos supor que queremos usar o método NotificationBuilder.SetCategory para categorizar uma notificação ao executar no Android 5.0 Lollipop (e posterior), mas ainda queremos que nosso aplicativo seja executado em versões anteriores do Android, como Android 4.1 Jelly Bean (em SetCategory que não está disponível). Referindo-se à tabela de versão do Android no início deste guia, vemos que o código de versão de build para Android 5.0 Lollipop é Android.OS.BuildVersionCodes.Lollipop. Para dar suporte a versões mais antigas do Android SetCategory em que não está disponível, nosso código pode detectar o nível de API em runtime e chamar SetCategory condicionalmente somente quando o nível da API for maior ou igual ao código de versão de build do Lollipop:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

Neste exemplo, a Estrutura de Destino do aplicativo é definida como Android 5.0 (Nível de API 21) e sua versão mínima do Android está definida como Android 4.1 (Nível de API 16). Como SetCategory está disponível no nível Android.OS.BuildVersionCodes.Lollipop da API e posterior, este código de exemplo chamará SetCategory somente quando estiver realmente disponível– ele não tentará chamar SetCategory quando o nível da API for 16, 17, 18, 19 ou 20. A funcionalidade é reduzida nessas versões anteriores do Android apenas na medida em que as notificações não são classificadas corretamente (porque não são categorizadas por tipo), mas as notificações ainda são publicadas para alertar o usuário. Nosso aplicativo ainda funciona, mas sua funcionalidade é ligeiramente diminuída.

Em geral, a versão de build marcar ajuda seu código a decidir em runtime entre fazer algo da nova maneira versus da maneira antiga. Por exemplo:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Não há uma regra rápida e simples que explique como reduzir ou modificar a funcionalidade do aplicativo quando ele é executado em versões mais antigas do Android que não têm uma ou mais APIs. Em alguns casos (como no SetCategory exemplo acima), é suficiente omitir a chamada à API quando ela não estiver disponível. No entanto, em outros casos, talvez seja necessário implementar uma funcionalidade alternativa para quando Android.OS.Build.VERSION.SdkInt for detectado ser menor que o nível de API que seu aplicativo precisa para apresentar sua experiência ideal.

Níveis e bibliotecas de API

Ao criar um projeto de biblioteca do Xamarin.Android (como uma biblioteca de classes ou uma biblioteca de associações), você pode definir apenas a configuração estrutura de destino – as configurações Versão mínima do Android e a versão de destino do Android não estão disponíveis. Isso ocorre porque não há nenhuma página do Manifesto do Android :

Somente a opção Compilar usando a versão do Android está disponível

As configurações De versão mínima do Android e Versão de destino do Android não estão disponíveis porque a biblioteca resultante não é um aplicativo autônomo – a biblioteca pode ser executada em qualquer versão do Android, dependendo do aplicativo com o qual ela está empacotada. Você pode especificar como a biblioteca deve ser compilada, mas não pode prever em qual nível de API de plataforma a biblioteca será executada. Com isso em mente, as seguintes práticas recomendadas devem ser observadas ao consumir ou criar bibliotecas:

  • Ao consumir uma biblioteca do Android – se você estiver consumindo uma biblioteca do Android em seu aplicativo, defina a configuração da Estrutura de Destino do aplicativo como um nível de API que seja pelo menos tão alto quanto a configuração da Estrutura de Destino da biblioteca.

  • Ao criar uma biblioteca do Android – se você estiver criando uma biblioteca do Android para uso por outros aplicativos, defina sua configuração da Estrutura de Destino para o nível mínimo de API necessário para compilar.

Essas práticas recomendadas são recomendadas para ajudar a evitar a situação em que uma biblioteca tenta chamar uma API que não está disponível em runtime (o que pode causar falha no aplicativo). Se você for um desenvolvedor de biblioteca, deverá se esforçar para restringir o uso de chamadas à API para um subconjunto pequeno e bem estabelecido da área total da superfície da API. Isso ajuda a garantir que sua biblioteca possa ser usada com segurança em uma ampla variedade de versões do Android.

Resumo

Este guia explicou como os níveis de API do Android são usados para gerenciar a compatibilidade de aplicativos em diferentes versões do Android. Ele forneceu etapas detalhadas para definir as configurações do projeto estrutura de destino do Xamarin.Android, versão mínima do Android e versão de destino do Android . Ele forneceu instruções para usar o Gerenciador de SDK do Android para instalar pacotes do SDK, incluiu exemplos de como escrever código para lidar com diferentes níveis de API em runtime e explicou como gerenciar níveis de API ao criar ou consumir bibliotecas do Android. Ele também forneceu uma lista abrangente que relaciona os níveis de API aos números de versão do Android (como Android 4.4), nomes de versão do Android (como Kitkat) e códigos de versão de build do Xamarin.Android.