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 caricate sui 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 non originariamente disponibili nell'SDK per queste versioni precedenti di Android.

Controllo delle versioni dell'API

A partire da Android 11 (livello API 30), i dispositivi Android includono un insieme di estensioni SDK. Quando vengono aggiunte nuove API, queste sono incluse in un livello API, ma possono essere incluse anche in un'estensione dell'SDK di una determinata versione. Ad esempio, l'API ACTION_PICK_IMAGES 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, che può essere una costante di Build.VERSION_CODES o una definita nella classe SdkExtensions (ad es. SdkExtensions.AD_SERVICES).

Determina quali estensioni SDK utilizzare

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

Le pagine di riferimento delle API di estensione SDK specificano la versione dell'estensione SDK più antica che la tua app può utilizzare per accedere a un'API. Se la documentazione specifica anche una versione della piattaforma Android (a cui viene fatto riferimento in base al 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 genere nell'SDK pubblico a partire da Android 13 (livello API 33), ma è disponibile anche su dispositivi con Android 11 (livello API 30) e versioni precedenti, a condizione che il dispositivo abbia almeno R Extensions versione 2:

Per utilizzare questa API, devi eseguire la compilazione in base a un SDK di almeno livello API 33 o di livello di estensione almeno 2.

Per utilizzare un SDK di estensione:

1. Cerca la versione minima delle estensioni di cui hai bisogno consultando la documentazione delle funzionalità e il riferimento all'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 corrispondente dell'estensione (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:

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

Verificare se sono disponibili estensioni SDK

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

Controllo in fase di esecuzione

La tua app può verificare in fase di esecuzione se le estensioni SDK sono disponibili per una determinata versione della piattaforma utilizzando il metodo getExtensionVersion(). Ad esempio, il seguente codice verifica 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;
}

È un'operazione 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 di selettore di foto nell'SDK pubblico, ma ci sono dispositivi con SDK_INT inferiore a 33 (ad esempio Android 11, 12 e 12L) che potrebbero anche accedere alle API se hanno versioni con estensione R di almeno 2.

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

Estensioni di Servizi pubblicitari

Analogamente al set generale di Estensioni SDK, il riferimento all'API AdServices talvolta indica che un'API fa parte di una versione di "Estensioni di servizi pubblicitari". A differenza delle Estensioni SDK generali, le Estensioni di servizi pubblicitari utilizzano la costante SdkExtensions.AD_SERVICES per determinare quale versione è installata 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 scoprire di più sulle funzionalità di Service Extensions per gli annunci e su come iniziare, consulta la documentazione di Service Extensions per gli annunci.

Metodi di utilità

In alcuni casi, le estensioni SDK dispongono di metodi di utilità Jetpack per verificare la disponibilità delle loro API di estensioni SDK. Ad esempio, puoi utilizzare una funzione della libreria Jetpack per verificare la disponibilità di PhotoPicker, che esegue l'astrazione dei controlli delle versioni condizionali.

Supporto degli strumenti

In Android Studio Flamingo | 2022.2.1 o versioni successive, lo strumento lint può cercare 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 e costanti delle estensioni SDK

La tabella seguente descrive in che modo i diversi set di estensioni SDK elencati nella documentazione di riferimento dell'API vengono mappati alle costanti che la tua app può utilizzare per verificare la disponibilità dell'API in fase di esecuzione. L'insieme generale di estensioni SDK per ogni SDK pubblico corrisponde ai valori di Build.VERSION_CODES.

Controllo tramite adb

Per controllare 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 corrispondente versione delle estensioni (3 in questo caso).