Estensioni SDK

Le estensioni SDK sfruttano i componenti di sistema modulari per aggiungere API all'SDK pubblico per determinati livelli API rilasciati in precedenza. Queste API vengono fornite ai dispositivi quando gli utenti finali ricevono gli aggiornamenti dei moduli tramite gli aggiornamenti di sistema di Google Play. Gli sviluppatori di app possono utilizzare queste API nelle loro app per fornire funzionalità aggiuntive che non erano originariamente disponibili nell'SDK per queste versioni precedenti di Android.

Controllo delle versioni delle API

A partire da Android 11 (livello API 30), i dispositivi Android includono un insieme di estensioni SDK. Quando vengono aggiunte nuove API, queste vengono incluse in un livello API, ma possono anche essere incluse in un'estensione SDK di una versione specifica. Ad esempio, l' ACTION_PICK_IMAGES API per il selettore di foto è stata aggiunta all'SDK pubblico in Android 13 (livello API 33), ma è disponibile anche tramite le estensioni SDK a partire dalla versione 2 delle estensioni R. I nomi delle estensioni SDK corrispondono a una costante intera, ovvero una costante di Build.VERSION_CODES o una definita nella classe SdkExtensions (ad esempio SdkExtensions.AD_SERVICES).

Determinare quali estensioni SDK utilizzare

Prima di poter utilizzare le API delle estensioni SDK, devi prima determinare quali SDK includono le API che supportano i casi d'uso della tua app.

Le pagine di riferimento delle API per le API delle estensioni SDK specificano la versione più recente dell'estensione SDK che la tua app può utilizzare per accedere a un'API. Se la documentazione specifica anche una versione della piattaforma Android (a cui si fa riferimento tramite il livello API), l'API è disponibile anche per tutti i dispositivi con quella versione di Android o versioni successive.

Ad esempio, ACTION_PICK_IMAGES è disponibile in generale nell'SDK pubblico a partire da Android 13 (livello API 33), ma è disponibile anche sui dispositivi con Android 11 (livello API 30), a condizione che il dispositivo abbia almeno la versione 2 delle estensioni R:

Per utilizzare questa API, devi eseguire la compilazione con un SDK di livello API 33 o superiore o di livello di estensione 2 o superiore.

Per utilizzare un SDK di estensione:

1. Cerca la versione minima delle estensioni di cui hai bisogno controllando la documentazione delle funzionalità e il riferimento API per le API che vuoi utilizzare.
2. Dopo aver determinato la versione dell'estensione richiesta per il tuo set di funzionalità, apri SDK Manager in Android Studio.
3. Seleziona la voce Piattaforma SDK Android con la versione dell'estensione corrispondente (o una versione successiva, poiché le API sono additive). Ad esempio: Piattaforma SDK Android 33, livello di estensione 4.

4. Dichiara questi valori nel file build.gradle.kts o build.gradle della tua app:

   Alla moda

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   Kotlin

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

Verificare se le estensioni SDK sono disponibili

La tua app può verificare quali versioni delle estensioni SDK sono disponibili in fase di runtime e, durante lo sviluppo, puoi cercare le versioni delle estensioni utilizzando i comandi di Android Debug Bridge (adb), come descritto nelle sezioni seguenti.

Verificare in fase di runtime

La tua app può verificare in fase di runtime se le estensioni SDK sono disponibili per una data versione della piattaforma utilizzando il getExtensionVersion() metodo. Ad esempio, il seguente codice verificherebbe se è disponibile la versione 2 o successiva dell'estensione SDK per Android 11 (livello API 30):

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.
}

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

È simile a un controllo basato su Build.VERSION.SDK_INT:

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

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

Questo controllo SDK_INT è ancora sicuro e valido, ma isPhotoPickerAvailable restituirebbe false su alcuni dispositivi anche se l'API di estensione è disponibile. Di conseguenza, il controllo SDK_INT non è ottimale e il controllo della versione dell'estensione è un modo migliore per verificare la disponibilità dell'API. Tutti i dispositivi con SDK_INT maggiore o uguale a 33 (Android 13 o versioni successive) hanno le API del selettore di foto nell'SDK pubblico, ma esistono dispositivi con SDK_INT inferiore a 33 (ad esempio Android 11, 12 e 12L) che potrebbero accedere alle API se hanno versioni dell'estensione R di almeno 2.

In questo caso, l'utilizzo di un controllo della versione dell'estensione può aiutare la tua app a fornire funzionalità aggiuntive a un maggior numero di utenti. Per un elenco di tutte le costanti che puoi utilizzare per verificare la presenza di determinate estensioni SDK su un dispositivo, consulta Nomi ed estensioni delle estensioni SDK costanti.

Estensioni dei servizi pubblicitari

Analogamente all'insieme generale di estensioni SDK, il riferimento API AdServices a volte indica che un'API fa parte di una versione di "Estensioni dei servizi pubblicitari". A differenza delle estensioni SDK generali, le estensioni dei servizi pubblicitari utilizzano la costante SdkExtensions.AD_SERVICES per determinare la versione presente su un dispositivo:

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

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

Per saperne di più sulle funzionalità delle estensioni dei servizi pubblicitari e su come iniziare, consulta la documentazione relativa alle estensioni dei servizi pubblicitari.

Metodi di utilità

In alcuni casi, le estensioni SDK hanno metodi di utilità Jetpack per verificare la disponibilità delle relative API. Ad esempio, puoi utilizzare una funzione della libreria Jetpack per verificare la disponibilità di PhotoPicker , che astrae i controlli delle versioni condizionali.

Supporto degli strumenti

In Android Studio Flamingo | 2022.2.1 o versioni successive, lo strumento lint può eseguire la scansione per rilevare problemi con le versioni delle estensioni SDK nell'ambito del controllo NewAPI. Inoltre, Android Studio può generare automaticamente i controlli delle versioni corretti per le API avviate utilizzando le estensioni SDK.

Nomi ed estensioni delle estensioni SDK

La tabella seguente descrive come i diversi insiemi di estensioni SDK elencati nella documentazione di riferimento delle API vengono mappati alle costanti che la tua app può utilizzare per verificare la disponibilità delle API in fase di runtime. L'insieme generale di estensioni SDK per ogni SDK pubblico viene mappato ai valori di Build.VERSION_CODES.

Verificare utilizzando adb

Per verificare quali estensioni SDK sono disponibili su un dispositivo utilizzando adb, esegui il seguente comando:

adb shell getprop | grep build.version.extensions

Dopo aver eseguito il comando, vedrai un output simile al seguente:

[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

Ogni riga mostra un'estensione SDK presente sul dispositivo insieme alla versione dell'estensione corrispondente (3 in questo caso).