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:
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:
- 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.
- Depois de determinar a versão da extensão necessária para o conjunto de recursos, abra o SDK Manager no Android Studio.
- 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.
Declare os seguintes valores no arquivo
build.gradle.kts
oubuild.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.
![](https://developer.android.com/static/images/guide/sdk-extensions/extensions-lint-check.png?authuser=7&hl=pt)
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).