Estensioni SDK

Le estensioni SDK sfruttano il sistema modulare componenti per aggiungere API all'SDK pubblico per alcuni livelli API rilasciati in precedenza. Queste API sono disponibili sui dispositivi quando gli utenti finali ricevono gli aggiornamenti dei moduli tramite Google Play sistema aggiornamenti. Per app gli sviluppatori possono utilizzare queste API nelle loro app per fornire che non era originariamente disponibile nell'SDK per i modelli precedenti tutte le versioni di Android.

Controllo delle versioni delle API

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

Determina quali estensioni SDK utilizzare

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

Le pagine di riferimento per le API SDK Extension specificano la versione più recente dell'SDK dell'estensione che l'app può usare per accedere a un'API. Se la documentazione specifica anche una versione della piattaforma Android (cui si fa riferimento al livello API), L'API è disponibile anche per tutti i dispositivi con quella versione di Android o superiore.

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

Le API che fanno parte di SDK Extensions mostrano la versione dell'estensione nell'API riferimento non web

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

Per utilizzare l'SDK di un'estensione:

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

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

    Alla moda

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

Controlla se sono disponibili le estensioni SDK

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

Controlla in fase di esecuzione

La tua app può controllare in fase di runtime se le estensioni SDK sono disponibili per un determinato della piattaforma utilizzando getExtensionVersion() . Ad esempio, il seguente codice controlla se l'estensione versione 2 o versioni successive per l'estensione SDK per Android 11 (livello API 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;
}

È un po' come fare un controllo basato su 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;
}

Questo assegno SDK_INT è ancora sicuro e valido, ma isPhotoPickerAvailable lo restituisce false su alcuni dispositivi anche se è disponibile l'API dell'estensione. Come risultato, il controllo SDK_INT non è ottimale e il controllo della versione dell'estensione un modo migliore per verificare la disponibilità delle API. Tutti i dispositivi con un valore superiore a SDK_INT o uguale a 33 (Android 13 o versioni successive) dispongono dell'API Photo Selecter nella SDK pubblico, ma ci sono dispositivi con SDK_INT minore di 33 (ad esempio Android 11, 12 e 12L) che potrebbero anche accedere alle API se hanno l'estensione R. versioni di almeno 2.

In questo caso, l'utilizzo di un controllo della versione dell'estensione può facilitare la pubblicazione dell'app funzionalità aggiuntive per un maggior numero di utenti. Consulta la sezione Nomi delle estensioni SDK e costanti per un elenco di tutte le costanti che puoi usare verifica la presenza di determinate estensioni SDK su un dispositivo.

Estensioni dei servizi pubblicitari

Analogamente al set generale delle estensioni SDK, il riferimento API AdServices indica a volte che un'API fa parte di una completamente gestita. Diversamente dalle estensioni SDK generali, le estensioni dei servizi pubblicitari utilizzano Costante di SdkExtensions.AD_SERVICES per determinare quale versione è presente su un 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;
}

Per saperne di più sulle funzionalità delle estensioni di servizi pubblicitari e su come ottenere consulta la sezione sulle estensioni dei servizi pubblicitari documentazione.

Metodi di utilità

In alcuni casi, le estensioni SDK dispongono di metodi di utilità Jetpack per controllare il delle loro API SDK Extension. Ad esempio, puoi utilizzare un modello Jetpack funzione libreria per verificare la presenza di PhotoSelettore disponibilità, che astrae i controlli condizionali della versione.

Assistenza per gli strumenti

In Android Studio Flamingo | 2022.2.1 o versioni successive, lo strumento Lint può analizzare problemi con le versioni delle estensioni SDK nell'ambito del controllo NewAPI. Inoltre, Android Studio può generare automaticamente i controlli della versione corretti per le API che con SDK Extensions.

Lo strumento lint segnala le istanze in cui il numero minimo di estensioni SDK non è stata soddisfatta la versione richiesta per chiamare un'API.

Nomi e costanti delle estensioni SDK

La seguente tabella descrive in che modo i diversi insiemi di estensioni SDK elencate nella documentazione di riferimento delle API mappa alle costanti che l'app può utilizzare per per controllare la disponibilità delle API in fase di runtime. L'insieme generale di estensioni SDK per ogni SDK pubblico è mappato ai valori Build.VERSION_CODES

Nome estensione SDK Costante Dispositivi idonei
Estensioni R VERSION_CODES.R Android 11 (livello API 30) e versioni successive
Estensioni S VERSION_CODES.S Android 12 (livello API 31) e versioni successive
Estensioni T VERSION_CODES.TIRAMISU Android 13 (livello API 33) e versioni successive
Estensioni dei servizi pubblicitari SdkExtensions.AD_SERVICES Android 13 (livello API 33) e versioni successive

Controlla con ADB

Per verificare quali estensioni SDK sono disponibili su un dispositivo utilizzando adb, esegui la 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 ai relativi versione delle estensioni corrispondente (in questo caso 3).