Extensões do SDK

As extensões do SDK usam componentes do sistema modular para adicionar APIs ao SDK público em alguns níveis de API lançados anteriormente. Essas APIs são introduzidas nos dispositivos quando os usuários finais recebem atualizações do módulo em atualizações do sistema do Google Play. Os desenvolvedores podem usar essas APIs nos apps para oferecer outros recursos que não estavam disponíveis originalmente no SDK das versões anteriores do Android.

Controle de versões da API

A partir do Android 11 (API de nível 30), os dispositivos Android incluem um conjunto de extensões do SDK. Quando novas APIs são adicionadas, elas são incluídas em um nível de API, mas também podem ser inseridas na extensão do SDK de uma versão específica. Por exemplo, a API ACTION_PICK_IMAGES do seletor de fotos foi adicionada ao SDK público no Android 13 (API de nível 33), mas também está disponível em extensões do SDK a partir da versão 2 das extensões R. Os nomes das extensões do SDK correspondem a uma constante de número inteiro, seja uma constante de Build.VERSION_CODES ou uma definida na classe SdkExtensions, como SdkExtensions.AD_SERVICES.

Definir as extensões do SDK a serem usadas

Antes de usar as extensões do SDK, é necessário definir quais SDKs incluem as APIs com suporte aos casos de uso do seu app.

As páginas de referência dessas APIs especificam a versão mais antiga da extensão do SDK que pode ser usada pelo app para acessar uma API. Se a documentação especifica uma versão da plataforma Android, indicada pelo nível da API, isso significa que essa API também está disponível para todos os dispositivos com essa versão do Android ou com outras mais recentes.

Por exemplo, ACTION_PICK_IMAGES está disponível de forma geral no SDK público a partir do Android 13 (API de nível 33), mas também está disponível em dispositivos com o Android 11 (API de nível 30) que tenham, no mínimo, a versão 2 da extensão R:

A versão das APIs que fazem parte das extensões do SDK é indicada nos documentos de referência da API

Para usar essa API, é necessário compilar com um SDK voltado para uma API de nível 33 ou extensão de nível 2, no mínimo.

Para usar um SDK de extensão, siga estas etapas:

  1. Confira a versão de extensão mínima necessária. Para isso, consulte a documentação do recurso e a Referência das APIs que você pretende usar.
  2. Depois de determinar a versão da extensão necessária para o conjunto de recursos, abra o SDK Manager no Android Studio.
  3. Selecione a entrada Android SDK Platform e a versão da extensão correspondente (ou uma versão mais recente, já que as APIs são incrementais). Por exemplo: Android SDK Platform 33, extensão de nível 4.

  4. Declare os seguintes valores no arquivo build.gradle.kts ou build.gradle do app:

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

    android {
    compileSdk = 33
    compileSdkExtension = 4
    ...
}

Conferir se as extensões do SDK estão disponíveis

O app pode conferir quais versões das extensões do SDK estão disponíveis no momento da execução. Durante o desenvolvimento, é possível descobrir as versões das extensões que usam comandos do Android Debug Bridge (adb), conforme descrito nas seções a seguir.

Conferir durante a execução

No momento da execução, o app pode conferir se as extensões do SDK estão disponíveis em determinada versão da plataforma usando o método getExtensionVersion(). Como exemplo, o código abaixo consulta se a versão 2 ou mais recente da extensão do SDK está disponível no Android 11 (API de nível 30):

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

Java

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

Esse processo é parecido com uma verificação do Build.VERSION.SDK_INT:

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

Java

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

Verificar o SDK_INT é uma abordagem segura e válida, mas isPhotoPickerAvailable retornaria "false" em alguns dispositivos, mesmo que a API de extensão estivesse disponível. Por esse motivo, verificar o SDK_INT não é o ideal. A melhor maneira de conferir a disponibilidade da API é consultar a versão da extensão. Todos os dispositivos com SDK_INT 33 ou mais recente (Android 13 ou versões mais recentes) têm a API Photo Picker no SDK público. Contudo, existem dispositivos com SDK_INT anterior à versão 33 (como o Android 11, 12 e 12L) que também podem acessar as APIs se tiverem, no mínimo, a versão 2 da extensão R.

Nesse caso, conferir a versão da extensão pode ajudar o app a oferecer mais recursos a um número maior de usuários. Consulte Nomes e constantes de extensões do SDK para encontrar uma lista com todas as constantes que podem ser usadas para conferir se um dispositivo tem extensões específicas do SDK.

Extensões dos serviços de anúncios

Assim como acontece no conjunto geral de extensões do SDK, às vezes a Referência da API AdServices indica que uma API faz parte de uma versão das extensões dos serviços de anúncios. Ao contrário das extensões gerais do SDK, as extensões dos serviços de anúncios usam a constante SdkExtensions.AD_SERVICES para determinar qual versão está presente em um dispositivo:

Kotlin

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Para saber mais sobre os recursos das extensões dos serviços de anúncios e como começar a usá-las, consulte a documentação das extensões dos serviços de anúncios.

Métodos utilitários

Em alguns casos, as extensões do SDK incluem métodos utilitários do Jetpack para conferir se as APIs correspondentes estão disponíveis. Por exemplo, você pode usar uma função da biblioteca Jetpack para conferir a disponibilidade de PhotoPicker, fazendo com que as verificações condicionais da versão deixem de ser necessárias.

Suporte a ferramentas

No Android Studio Flamingo | 2022.2.1 ou mais recente, a ferramenta lint pode detectar problemas nas versões das extensões do SDK enquanto confere a NewAPI. Além disso, o Android Studio pode executar automaticamente a verificação de versão das APIs que são iniciadas usando extensões do SDK.

A ferramenta lint sinaliza instâncias em que a versão mínima da extensão do SDK necessária para chamar uma API não foi encontrada.

Nomes e constantes das extensões do SDK

A tabela abaixo descreve como os diferentes conjuntos de extensões do SDK listados na documentação de referência da API correspondem a constantes que podem ser usadas pelo app para consultar a disponibilidade da API no momento da execução. O conjunto geral de extensões do SDK para cada SDK público corresponde aos valores de Build.VERSION_CODES.

Nome da extensão do SDK Constante Dispositivos qualificados
Extensões R VERSION_CODES.R Android 11 (API de nível 30) e versões mais recentes
Extensões S VERSION_CODES.S Android 12 (API de nível 31) e versões mais recentes
Extensões T VERSION_CODES.TIRAMISU Android 13 (API de nível 33) e versões mais recentes
Extensões dos serviços de anúncios SdkExtensions.AD_SERVICES Android 13 (API de nível 33) e versões mais recentes

Verificar usando o adb

Para conferir quais extensões do SDK estão disponíveis em um dispositivo usando o adb, execute este comando:

adb shell getprop | grep build.version.extensions

Após executar o comando, você vai ver uma saída parecida com a seguinte:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

Cada linha mostra uma extensão do SDK presente no dispositivo e a versão correspondente (que nesse caso é 3).