Extensions SDK

Les extensions SDK exploitent des composants système modulaires afin d'ajouter des API au SDK public pour certains niveaux d'API déjà publiés. Ces API sont mises à la disposition des appareils lorsque les utilisateurs finaux reçoivent des mises à jour de module via les mises à jour du système Google Play. Les développeurs d'applications peuvent utiliser ces API dans leurs applications pour fournir des fonctionnalités supplémentaires qui n'étaient pas disponibles à l'origine dans le SDK pour ces versions antérieures d'Android.

Gestion des versions de l'API

À partir d'Android 11 (niveau d'API 30), les appareils Android incluent un ensemble d'extensions SDK. Lorsque de nouvelles API sont ajoutées, elles sont incluses dans un niveau d'API, mais elles peuvent également l'être dans une extension SDK d'une version particulière. Par exemple, l'API ACTION_PICK_IMAGES du sélecteur de photos a été ajoutée au SDK public dans Android 13 (niveau d'API 33), mais elle est également disponible via des extensions SDK à partir de la version 2 des extensions R. Les noms des extensions SDK correspondent à une constante entière (soit une constante de Build.VERSION_CODES, soit une constante définie dans la classe SdkExtensions, comme SdkExtensions.AD_SERVICES).

Déterminer les extensions SDK à utiliser

Avant de pouvoir utiliser des API SDK Extension, vous devez déterminer les SDK qui incluent les API compatibles avec les cas d'utilisation de votre application.

Les pages de documentation de référence des API SDK Extension spécifient la version d'extension SDK la plus ancienne que votre application peut utiliser pour accéder à une API. Si la documentation indique également une version de plate-forme Android (référencée par un niveau d'API), cette API est également disponible pour tous les appareils qui exécutent cette version d'Android ou une version ultérieure.

Par exemple, ACTION_PICK_IMAGES est disponible en général dans le SDK public à partir d'Android 13 (niveau d'API 33), mais également sur les appareils jusqu'à Android 11 (niveau d'API 30) à condition que l'appareil dispose au minimum de la version 2 des extensions R :

Les API qui font partie des extensions SDK affichent leur version dans leur documentation de référence.

Pour utiliser cette API, vous devez effectuer la compilation avec un SDK dont le niveau d'API minimum est 33 ou dont le niveau d'extension minimum est 2.

Pour utiliser un SDK d'extension, procédez comme suit :

  1. Recherchez la version minimale des extensions dont vous avez besoin en consultant la documentation sur les fonctionnalités et la documentation de référence des API que vous souhaitez utiliser.
  2. Une fois que vous avez déterminé la version d'extension requise pour votre ensemble de fonctionnalités, ouvrez SDK Manager dans Android Studio.
  3. Sélectionnez l'entrée "Android SDK Platform" avec la version de l'extension correspondante (ou une version ultérieure, car les API sont additives). Exemple : Android SDK Platform 33, niveau d'extension 4.

  4. Déclarez les valeurs suivantes dans le fichier build.gradle.kts ou build.gradle de votre application :

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

Vérifier si des extensions SDK sont disponibles

Votre application peut vérifier quelles versions d'extension SDK sont disponibles au moment de l'exécution. Lors du développement, vous pouvez rechercher les versions d'extension à l'aide de commandes Android Debug Bridge (adb), comme il est décrit dans les sections suivantes.

Vérifier au moment de l'exécution

Au moment de l'exécution, votre application peut vérifier si des extensions SDK sont disponibles pour une version de plate-forme donnée à l'aide de la méthode getExtensionVersion(). Par exemple, le code suivant permet de vérifier si la version d'extension 2 ou ultérieure de SDK Extension Android 11 (niveau d'API 30) est disponible :

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

Cela revient à effectuer une vérification basée sur 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;
}

Cette vérification SDK_INT est toujours sûre et valide, mais isPhotoPickerAvailable affichera la valeur "false" sur certains appareils même si l'API d'extension est disponible. La vérification SDK_INT n'est donc pas optimale. La vérification de la version de l'extension est un meilleur moyen de vérifier la disponibilité de l'API. Tous les appareils dont la version de SDK_INT est supérieure ou égale à 33 (Android 13 ou version ultérieure) disposent des API du sélecteur de photos dans le SDK public. Cependant, certains appareils dont la version de SDK_INT est inférieure à 33 (Android 11, 12 et 12L, par exemple) peuvent également accéder aux API si leur version de l'extension R est au minimum 2.

Dans ce cas, la vérification de la version de l'extension peut aider votre application à fournir des fonctionnalités supplémentaires à davantage d'utilisateurs. Consultez Noms et constantes des extensions du SDK pour obtenir la liste de toutes les constantes que vous pouvez utiliser pour rechercher certaines extensions SDK sur un appareil.

Extensions de services publicitaires

À l'instar de l'ensemble général d'extensions SDK, la documentation de référence de l'API AdServices indique parfois qu'une API fait partie d'une version "Extensions de services publicitaires". Contrairement aux extensions SDK générales, les extensions de services publicitaires utilisent la constante SdkExtensions.AD_SERVICES pour déterminer la version installée sur un appareil :

Kotlin

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

Java

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

Pour en savoir plus sur les fonctionnalités des extensions de services publicitaires et sur leur utilisation, consultez la documentation sur les extensions de services publicitaires.

Méthodes utilitaires

Dans certains cas, les extensions SDK disposent de méthodes utilitaires Jetpack pour vérifier la disponibilité de leurs API SDK Extension. Par exemple, vous pouvez utiliser une fonction de bibliothèque Jetpack pour vérifier la disponibilité de PhotoPicker, ce qui élimine les vérifications de version conditionnelles.

Prise en charge des outils

Dans Android Studio Flamingo | 2022.2.1 ou version ultérieure, l'outil lint peut rechercher les problèmes liés aux versions de l'extension SDK lors de sa vérification NewAPI. En outre, Android Studio peut générer automatiquement les vérifications de version correctes pour les API lancées à l'aide d'extensions SDK.

L'outil lint signale les instances pour lesquelles la version minimale des extensions SDK requise pour appeler une API n'a pas été atteinte.

Noms et constantes des extensions SDK

Le tableau suivant décrit la correspondance entre les différents ensembles d'extensions SDK listés dans la documentation de référence de l'API et les constantes que votre application peut utiliser pour vérifier la disponibilité de l'API au moment de l'exécution. L'ensemble général d'extensions SDK pour chaque SDK public correspond aux valeurs de Build.VERSION_CODES.

Nom de l'extension SDK Constante Appareils éligibles
Extensions R VERSION_CODES.R Android 11 (niveau d'API 30) ou version ultérieure
Extensions S VERSION_CODES.S Android 12 (niveau d'API 31) ou version ultérieure
Extensions T VERSION_CODES.TIRAMISU Android 13 (niveau d'API 33) ou version ultérieure
Extensions de services publicitaires SdkExtensions.AD_SERVICES Android 13 (niveau d'API 33) ou version ultérieure

Effectuer une vérification avec adb

Pour vérifier quelles sont les extensions SDK disponibles sur un appareil à l'aide d'adb, exécutez la commande suivante :

adb shell getprop | grep build.version.extensions

Une fois la commande exécutée, vous obtenez un résultat semblable à ceci :

[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

Chaque ligne affiche une extension SDK présente sur l'appareil, ainsi que la version des extensions correspondantes (trois dans ce cas).