Estensioni SDK

Le estensioni SDK sfruttano i componenti di sistema modulari per aggiungere API all'SDK pubblico per alcuni livelli API rilasciati in precedenza. Queste API vengono fornite ai dispositivi quando gli utenti finali ricevono aggiornamenti dei moduli tramite gli aggiornamenti di sistema di Google Play. Gli sviluppatori di app possono utilizzare queste API nelle proprie 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. Le nuove API aggiunte sono incluse in un livello API, ma possono essere incluse anche in un'estensione 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, una costante di Build.VERSION_CODES o una definita nella classe SdkExtensions (ad esempio SdkExtensions.AD_SERVICES).

Determina quali estensioni SDK utilizzare

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

Le pagine di riferimento per le API SDK Extensions specificano la prima versione dell'estensione SDK che l'app può utilizzare per accedere a un'API. Se la documentazione specifica anche una versione della piattaforma Android (a cui fa riferimento il livello API), l'API è disponibile anche per tutti i dispositivi su cui è installata quella versione di Android o successiva.

Ad esempio, ACTION_PICK_IMAGES è disponibile generalmente nell'SDK pubblico a partire da Android 13 (livello API 33), ma è disponibile anche sui dispositivi fino ad Android 11 (livello API 30), purché il dispositivo presenti almeno le estensioni R versione 2:

Per utilizzare questa API, devi eseguire la compilazione su un SDK con almeno il livello API 33 o il livello estensione 2.

Per utilizzare un SDK di estensione, procedi nel seguente modo:

1. Per conoscere la versione minima delle estensioni necessaria, consulta la documentazione sulle funzionalità e il riferimento API per le API che vuoi utilizzare.
2. Dopo aver determinato la versione dell'estensione richiesta per il 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 superiore, poiché le API sono cumulative). Ad esempio: Piattaforma SDK Android 33, livello estensione 4.

4. Dichiara questi valori nel file build.gradle.kts o build.gradle dell'app:

   Trendy

   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 dell'estensione SDK sono disponibili in fase di runtime e, durante lo sviluppo, puoi cercare le versioni delle estensioni utilizzando i comandi Android Debug Bridge (adb), come descritto nelle sezioni seguenti.

Controlla in fase di runtime

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

Si tratta di un'operazione simile a quella di 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 restituirà false su alcuni dispositivi anche se l'API dell'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) dispongono delle API di selezione delle 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 dispongono di versioni dell'estensione R di almeno 2.

In questo caso, l'uso di un controllo della versione dell'estensione può aiutare l'app a offrire funzionalità aggiuntive a un maggior numero di utenti. Consulta la sezione Costanti e nomi 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 dei servizi pubblicitari

Analogamente all'insieme generale di estensioni SDK, il riferimento dell'API AdServices a volte indica che un'API fa parte di una versione "Ad Services Extensions". A differenza delle estensioni SDK generali, le estensioni di servizi pubblicitari utilizzano la costante SdkExtensions.AD_SERVICES per determinare quale 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 ulteriori informazioni sulle funzionalità delle estensioni di servizi annunci e su come iniziare, consulta la documentazione sulle estensioni di servizi annunci.

Metodi di utilità

In alcuni casi, le estensioni SDK prevedono metodi dell'utilità Jetpack per verificare la disponibilità delle relative API SDK Extensions. Ad esempio, puoi utilizzare una funzione di libreria Jetpack per verificare la disponibilità di Photo Picker, che astrae i controlli della versione condizionale.

Assistenza per gli strumenti

In Android Studio Flamingo | 2022.2.1 o versioni successive, lo strumento lint può rilevare problemi con le versioni dell'estensione SDK nell'ambito del controllo NewAPI. Inoltre, Android Studio può generare automaticamente i controlli della versione corretti per le API lanciate utilizzando le estensioni SDK.

Nomi e costanti delle estensioni SDK

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

Controllo con ADB

Per verificare quali estensioni SDK sono disponibili su un dispositivo che utilizza adb, esegui questo 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 relativa versione delle estensioni (3 in questo caso).