API Level : qu'est-ce que c'est, versions d'API et targetSdk

Qu'est-ce que l'API Level Android ?

API Level Android est un identifiant entier attribué à chaque version publique de l'API Android Framework. La première version Android 1.0 avait l'API Level 1, Android 1.5 — API Level 3, Android 2.2 — API Level 8, Android 4.0 — API Level 14, Android 8.0 — API Level 26, Android 12 — API Level 31, Android 14 — API Level 34, Android 15 — API Level 35, Android 16 (2025) — API Level 36. Chaque nouvel API Level peut ajouter de nouvelles classes, méthodes, constantes, permissions et modifier le comportement des existantes.

L'API Level n'augmente pas strictement de 1 à chaque version. Par exemple, Android 4.4W (Wear) a l'API 20, tandis qu'Android 5.0 — API 21. Les écarts sont liés aux itérations internes et aux appareils Wear OS. Pour le développeur, il est important de connaître non pas le nom de la version (KitKat, Lollipop, Tiramisu), mais son API Level — c'est ce qui est utilisé dans le code pour les vérifications de compatibilité.

Le but principal de l'API Level est la rétrocompatibilité. Une application compilée contre l'API 34 peut fonctionner sur des appareils avec API 34 et inférieurs (si elle n'utilise pas de nouvelles API sans vérification). Android Runtime (ART) vérifie les appels d'API au niveau système et applique les changements de comportement en fonction du targetSdkVersion de l'application.

Comment Android gère l'API Level

Lors de l'installation d'une application, PackageManager vérifie que l'API Level de l'appareil >= minSdkVersion du AndroidManifest.xml. Si la condition n'est pas remplie — l'installation est bloquée avec le message "App not installed". Pendant l'exécution, Android Runtime surveille les appels d'API qui nécessitent un API Level supérieur et génère NoSuchMethodError ou UnsatisfiedLinkError si la méthode est absente de la version actuelle.

minSdk, targetSdk, compileSdk : différences et rôle de chaque paramètre

Dans le fichier build.gradle (Module: app), le développeur spécifie trois paramètres d'API Level : minSdkVersion, targetSdkVersion et compileSdkVersion. Les confondre est l'une des erreurs les plus courantes chez les développeurs Android débutants. Chaque paramètre est responsable d'un aspect différent de la compatibilité, et leurs valeurs doivent être cohérentes.

minSdkVersion

minSdkVersion est l'API Level minimum auquel l'application peut être installée et exécutée. Les appareils avec un API Level inférieur à minSdk ne voient pas l'application dans Google Play et ne peuvent pas l'installer. La valeur est choisie en fonction du public cible : minSdk 21 (Android 5.0) couvre 97 % des appareils, minSdk 26 (Android 8.0) — environ 85 %, minSdk 31 (Android 12) — environ 55 % (données d'Android Studio Distribution Dashboard, 2026). Plus minSdk est bas, plus la couverture est large, mais plus le code de rétrocompatibilité est nécessaire.

targetSdkVersion

targetSdkVersion est l'API Level contre lequel l'application a été testée. Android utilise targetSdk pour appliquer les changements de comportement : si l'application spécifie targetSdk 33, le système active tous les changements de comportement introduits dans l'API 33. Si targetSdk est 31, le système n'applique pas les changements des API 32-33, préservant la compatibilité avec l'ancien comportement. C'est le paramètre le plus important pour la sécurité : Google Play exige targetSdk ne dépassant pas 1 an depuis l'API Level actuel.

compileSdkVersion

compileSdkVersion est la version du SDK Android contre laquelle le code est compilé. Elle détermine quelles API sont disponibles au moment de la compilation. compileSdk doit être >= targetSdk et, idéalement, égal au dernier API Level stable. Augmenter compileSdk n'affecte pas le comportement à l'exécution — seulement la disponibilité de nouvelles API pour le compilateur. Après avoir augmenté compileSdk, il faut vérifier le code pour les API obsolètes et les nouvelles exigences de permissions.

// build.gradle.kts — exemple de configuration d'API Level
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26      // Android 8.0
        targetSdk = 36    // Android 16
        versionCode = 1
        versionName = "1.0.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

Dans l'exemple build.gradle.kts, compileSdk = 36 (le plus récent au moment de la rédaction), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 donne accès à toutes les API d'Android 16. targetSdk 36 active tous les changements de comportement d'Android 16. minSdk 26 couvre ~85 % des appareils. AndroidX Activity KTX et AppCompat assurent la rétrocompatibilité pour les fragments et les thèmes.

AndroidManifest.xml

Les paramètres minSdk et targetSdk peuvent également être spécifiés dans AndroidManifest.xml, mais les projets modernes utilisent build.gradle — les valeurs de Gradle remplacent le manifeste. Dans le manifeste, il peut être utile de spécifier pour les bibliothèques et modules qui n'utilisent pas la configuration de build Gradle.

Changements de comportement : comment targetSdk affecte le comportement de l'application

Les changements de comportement sont des modifications du fonctionnement du système Android qui sont appliquées uniquement aux applications avec targetSdk >= un certain API Level. Chaque nouvelle version d'Android introduit des changements de comportement qui peuvent casser les applications existantes si elles ne sont pas mises à jour. C'est un mécanisme de sécurité clé d'Android : les anciennes applications continuent de fonctionner comme avant, les nouvelles suivent les règles actuelles.

Principaux changements de comportement par version

Android 10 (API 29) — Scoped Storage : les applications avec targetSdk 29+ n'ont pas d'accès direct au système de fichiers partagé, seulement via MediaStore, SAF ou leur propre stockage. Android 11 (API 30) — Package Visibility : filtre de paquets, les applications ne voient que les paquets installés avec lesquels elles interagissent. Android 12 (API 31) — Foreground Service Notification : tous les services de premier plan doivent afficher une notification dans les 10 secondes suivant le démarrage. Android 13 (API 33) — POST_NOTIFICATIONS : permission d'exécution pour les notifications push. Android 14 (API 34) — Foreground Service Types : déclaration obligatoire du type de service de premier plan dans le manifeste.

// Gestion des changements de comportement d'Android 13 (API 33) : POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // L'autorisation POST_NOTIFICATIONS ne fonctionne qu'avec API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // En dessous de l'API 33, l'autorisation n'est pas requise
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Autorisation déjà accordée, les notifications peuvent être envoyées
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Afficher l'explication de pourquoi l'autorisation est nécessaire
                activity.showRationale()
            }

            else -> {
                // Demander l'autorisation
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Créer et afficher la notification
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Notification")
            .setContentText("Nouveau message")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Enregistrer requestPermissionLauncher dans l'Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Autorisation accordée
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Exemple de gestion de POST_NOTIFICATIONS en Kotlin : vérifier Build.VERSION.SDK_INT >= TIRAMISU, demander la permission d'exécution via ActivityResultContracts.RequestPermission, traiter le résultat dans un callback. Sans cette permission, une application avec targetSdk 33+ ne peut pas afficher les notifications push. En dessous de l'API 33, la permission n'est pas requise — le code de vérification empêche l'appel d'API indisponibles.

Scoped Storage (Android 10+)

Scoped Storage est l'un des changements de comportement les plus significatifs. À partir de l'API 29 (targetSdk 29+), l'application ne peut pas obtenir d'accès direct aux fichiers dans les répertoires Pictures, Downloads, Music et Documents. Au lieu de cela, on utilise MediaStore pour les médias, SAF (Storage Access Framework) pour les fichiers arbitraires et getExternalFilesDir() pour son propre stockage. L'exception concerne les applications avec la permission MANAGE_EXTERNAL_STORAGE, qui nécessite l'approbation de Google Play.

Exigences de Google Play pour l'API Level et targetSdk

Google Play établit des exigences obligatoires de targetSdkVersion pour publier des applications. Depuis août 2024, Google Play exige targetSdkVersion >= API 33 (Android 13). Chaque année, le seuil augmente : les nouvelles applications et mises à jour doivent spécifier targetSdk ne dépassant pas 1 an depuis l'API Level principal actuel. La violation de l'exigence entraîne le blocage de la publication et le retrait de l'application du magasin.

Pourquoi Google Play durcit les exigences

La raison principale est la sécurité. Chaque nouvel API Level Android introduit des changements de comportement qui ferment des vecteurs d'attaque : Scoped Storage (API 29) empêche le vol de fichiers, POST_NOTIFICATIONS (API 33) protège contre les notifications spam, Foreground Service Types (API 34) limite les services d'arrière-plan cachés. Les applications avec un targetSdk bas ne reçoivent pas ces protections et deviennent une menace pour les utilisateurs. Google Play ne peut pas permettre des applications obsolètes sur des appareils modernes.

Vérification de la conformité aux exigences

Google Play Console vérifie targetSdkVersion lors du téléchargement d'APK/AAB. Si targetSdk est inférieur à l'exigence — la console bloque la publication avec le message : "Your app currently targets API level X and must target at least API level Y". Le développeur doit mettre à jour build.gradle, recompiler l'application, tester les changements de comportement et la télécharger à nouveau. Le format AAB est recommandé pour toutes les nouvelles publications (obligatoire depuis août 2021).

Vérification de l'API Level dans le code : Build.VERSION.SDK_INT

Build.VERSION.SDK_INT est une constante entière statique contenant l'API Level de l'appareil sur lequel l'application s'exécute. C'est l'outil principal pour les vérifications de version Android à l'exécution. Build.VERSION_CODES contient des constantes nommées pour chaque API Level : VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). La comparaison via if (SDK_INT >= VERSION_CODES.TIRAMISU) est le modèle standard.

// Exemples de vérification d'API Level dans le code Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Vérification de base de l'API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Appel d'API adaptatif avec vérification
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable n'est disponible qu'avec API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback pour les anciens appareils
    }

    // 3. Vérification de l'autorisation POST_NOTIFICATIONS (API 33+ uniquement)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Sélection du fournisseur d'images selon l'API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ utilise PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ utilise Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy : ACTION_GET_CONTENT (toutes versions)
                "get_content"
            }
        }
    }

    // 5. Vérification style Java via @TargetApi (pour la rétrocompatibilité)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Le comportement de Scoped Storage dépend de targetSdk, pas de SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informations de build pour l'analytique
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// Test
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

La classe ApiLevelHelper illustre tous les principaux modèles de vérification d'API Level : isAtLeastTiramisu avec SDK_INT >= VERSION_CODES, getAdaptiveIcon avec fallback pour les anciennes versions, getImagePickerProvider avec when à plusieurs branches, getDeviceApiInfo pour l'analytique. La règle clé est de ne pas appeler de nouvelles API sans vérifier SDK_INT, sinon l'application plantera avec NoSuchMethodError sur les anciens appareils.

ANT (Android New API) et lint

Android Studio inclut l'analyseur statique lint, qui avertit de l'utilisation d'API au-dessus de minSdkVersion. Si une méthode est appelée sans vérification de SDK_INT, lint la souligne comme une erreur : "Call requires API level 34 (current min is 26)". Solutions : ajouter @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) à la méthode ou une vérification if de SDK_INT. @TargetApi est une annotation obsolète, @RequiresApi est recommandé.

Tableau de correspondance entre l'API Level et les versions d'Android

Le tableau de l'API Level est un outil de référence pour le développeur. Connaissant l'API Level de l'appareil, on peut déterminer la version d'Android et les fonctionnalités disponibles. Le tableau répertorie toutes les principales versions d'Android de l'API Level 1 (2008) à l'API Level 36 (2025). Les noms de code (Cupcake, Donut, Tiramisu, VanillaIceCream) sont utilisés en interne chez Google et dans VERSION_CODES.

Tableau : API Levels seuils pour les changements de comportement

Le tableau suivant montre les API Levels clés qui introduisent des changements de comportement cassant la rétrocompatibilité lors de l'augmentation de targetSdk :