compileSdkVersion: basis, nieuwe API's en configuratie in Gradle

Wat is compileSdkVersion in Android?

compileSdkVersion — een integer parameter in build.gradle die aangeeft tegen welke versie van de Android SDK de code gecompileerd moet worden. Wanneer je code schrijft die klassen uit android.* of androidx.* gebruikt, controleert de compiler ze met de API's die beschikbaar zijn in de opgegeven compileSdk-versie. Als een methode verscheen in API 36 en compileSdk = 35 is, wordt de code niet gecompileerd. Als compileSdk = 36 is — wordt de code gecompileerd, maar op een apparaat met API 35 zal het aanroepen van deze methode zonder controle een fout veroorzaken.

compileSdkVersion wordt geladen uit Android SDK Platform, geïnstalleerd via SDK Manager in Android Studio. Elk API Level heeft zijn eigen platform: android-21, android-29, android-34, android-35, android-36. Het platform bevat android.jar — een set klassen, methoden en constanten waarmee de Kotlin/Java-compiler werkt. Als het platform niet is geïnstalleerd, zal Gradle het automatisch downloaden via sdkmanager bij de eerste build.

AGP (Android Gradle Plugin) versie 8.7+ raadt aan om compileSdk als een geheel getal op te geven via compileSdk = 36 in Kotlin DSL, zonder het android- voorvoegsel. compileSdk kan ook worden opgegeven via compileSdkVersion 36 in Groovy DSL of compileSdkPreview voor preview-versies van de SDK (developer previews). compileSdkPreview wordt gebruikt voor het testen van aankomende API Levels vóór de officiële release.

// build.gradle.kts — compileSdkVersion configuratie
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — laatste stabiele API Level (Android 16)
    compileSdk = 36

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

// Alternatief: compileSdkPreview voor preview-versies
// compileSdkPreview = "Baklava"

In het voorbeeld geeft compileSdk = 36 toegang tot alle API's van Android 16 (Baklava). Android SDK Platform 36 moet geïnstalleerd zijn in SDK Manager. compileSdkPreview met de naam "Baklava" kan worden gebruikt voor het testen van onstable API's vóór de officiële release van het platform. Na de release wordt preview vervangen door stabiele compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Drie API Level parameters in build.gradle — compileSdkVersion, targetSdkVersion en minSdkVersion — worden vaak verward. Elk is verantwoordelijk voor een ander aspect van compatibiliteit, en hun waarden moeten worden afgestemd volgens de regel compileSdk >= targetSdk >= minSdk. minSdk — ondergrens: apparaten eronder zien de app niet. targetSdk — testpunt: behavioural changes worden tot dit niveau ingeschakeld. compileSdk — plafond: API's boven dit niveau zijn niet beschikbaar voor de compiler.

Belangrijke praktische regel: compileSdk kan worden verhoogd zonder enig testen op apparaten. Dit is een veilige bewerking die alleen de compiler een nieuwe versie van android.jar geeft. Het enige risico — deprecated API's die kunnen worden verwijderd in de nieuwe versie van het platform, maar dit wordt ontdekt in de compilatiefase en is eenvoudig te repareren. Het verhogen van targetSdk vereist daarentegen een volledige QA-cyclus.

Waarom kan compileSdk hoger zijn dan targetSdk? Stel je voor dat Android 16 (API 36) is uitgebracht met nieuwe API's die je in code wilt gebruiken, maar de behavioural changes van API 36 heb je nog niet getest. Je stelt compileSdk = 36 in (nieuwe API's beschikbaar), targetSdk = 35 (behavioural changes van API 36 uitgeschakeld). De code wordt gecompileerd, gebruikt nieuwe methoden onder SDK_INT-controles, en behavioural changes van API 36 zullen de app niet breken omdat targetSdk = 35.

Voorbeelden van correcte combinaties

compileSdk = 36, targetSdk = 36, minSdk = 26 — volledige compatibiliteit met de nieuwste API's en behavioural changes, bereik 85% apparaten. compileSdk = 36, targetSdk = 34, minSdk = 26 — nieuwe API's beschikbaar, behavioural changes alleen tot API 34. compileSdk = 35, targetSdk = 36 — incorrect: compileSdk lager dan targetSdk, API 36 niet beschikbaar, hoewel behavioural changes 36 actief zijn.

Hoe compileSdkVersion updaten: stap-voor-stap handleiding

Het updaten van compileSdkVersion — een van de eenvoudigste en veiligste bewerkingen in een Android-project. In tegenstelling tot targetSdk, vereist het geen langdurig testen van behavioural changes. Er zijn echter een paar stappen die moeten worden uitgevoerd om compilatiefouten en deprecated-waarschuwingen te voorkomen.

Stap 1 — installeer het nieuwe platform via SDK Manager in Android Studio: Tools → SDK Manager → SDK Platforms → selecteer het nieuwe API Level. Als je het platform niet installeert, zal Gradle proberen het automatisch te downloaden, maar dit kan de eerste build vertragen. Stap 2 — wijzig compileSdk in build.gradle naar de nieuwe waarde. Stap 3 — voer de build uit (Build → Make Project) en herstel compilatiefouten.

Stap 4 — controleer deprecated API's. Na het verhogen van compileSdk kunnen sommige methoden zijn gemarkeerd met @Deprecated met de notitie "removed in API X". Android Studio markeert ze met doorhaling en geeft een waarschuwing. Vervang deprecated-aanroepen door nieuwe alternatieven. Als het alternatief een hoger API Level vereist dan minSdk, voeg dan een runtime-controle toe. Stap 5 — controleer dependencies: sommige bibliotheken kunnen een specifieke compileSdk-versie vereisen. AGP 8.7+ raadt compileSdk = 36 aan.

// Na het verhogen van compileSdk: vervangen van deprecated API's
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // VOOR: deprecated methode (kan worden verwijderd in nieuwe API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Kan deprecated zijn in API 36
    }

    // NA: nieuw alternatief (indien beschikbaar)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nieuwe API uit compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Voorbeeld van nieuwe API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

De klasse CompileSdkMigration toont het correcte migratiepatroon. De oude methode memoryClass kan worden verwijderd in de nieuwe API — de compiler geeft een fout. Het nieuwe alternatief getMemoryClassSafe is alleen beschikbaar op API 36+, dus het wordt aangeroepen onder de controle SDK_INT >= BAKLAVA. Voor oude apparaten wordt fallback gebruikt met @Suppress("DEPRECATION").

Werken met nieuwe API's: conditional checks en fallback

Nieuwe API's, beschikbaar dankzij het verhogen van compileSdkVersion, kunnen niet direct worden aangeroepen als minSdkVersion lager is dan dit API Level. Zonder runtime-controle zal de app crashen met AbstractMethodError, NoSuchMethodError of VerifyError op oudere apparaten. Het belangrijkste beschermingsmechanisme — controle van Build.VERSION.SDK_INT met het aanroepen van de nieuwe API alleen bij voldoende API Level en fallback voor oudere versies.

AndroidX biedt backports van veel nieuwe API's, waardoor moderne methoden kunnen worden gebruikt zelfs bij een lage compileSdk. Bijvoorbeeld, Activity Result API van androidx.activity:activity-ktx:1.9.3 werkt op alle versies van Android vanaf API 14. NotificationCompat van AndroidX maakt het mogelijk moderne meldingen te gebruiken op oude API's. PhotoPicker is beschikbaar via ActivityResultContracts.PickVisualMedia vanaf API 34+.

// Veilig aanroepen van nieuwe API met compileSdk 36 en minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: nieuwe methode voor kleurverwerking
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nieuwe API uit compileSdk 36 — vereist API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: handmatige formattering voor oude API's
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport niet vereist — SDK_INT-controle
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Gebruik in Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

De klasse NewApiHelper demonstreert het veilig aanroepen van de nieuwe API Color.toArgbHexString (hypothetische API 36) met fallback-formattering voor oudere versies. Het belangrijkste principe: compileSdk geeft toegang tot het aanroepen van nieuwe methoden in code, maar de runtime-controle SDK_INT beschermt tegen crashes op oudere apparaten. Zonder SDK_INT-controle zal de app met minSdk 26 en compileSdk 36 crashen op Android 8-15.

AGP (Android Gradle Plugin) en compileSdkVersion

Android Gradle Plugin (AGP) — het belangrijkste build-gereedschap voor Android-apps. Elke AGP-versie ondersteunt een bepaald bereik van compileSdkVersion. AGP 8.7.x (uitgebracht in 2026) vereist compileSdk >= 34 en raadt compileSdk = 36 aan. AGP 8.5.x ondersteunt compileSdk 33-35. Als compileSdk lager is dan het minimum voor AGP, zal de build eindigen met de fout "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) is ook gekoppeld aan compileSdkVersion. Als het project native code in C/C++ via NDK gebruikt, bepaalt compileSdk de versie van header-bestanden en bibliotheken. NDK r27+ raadt compileSdk 36 aan. Voor bibliotheken met .so-bestanden beïnvloedt compileSdk het minimale API Level voor native code via APP_MIN_SDK_VERSION in Application.mk.

Gradle (7.6+) en Kotlin (2.0+) beïnvloeden ook de compatibiliteit met compileSdk. AGP 8.7+ vereist Gradle 8.9+ en Kotlin 2.0+. Bij het verhogen van compileSdk wordt aanbevolen AGP, Gradle en Kotlin te updaten naar de nieuwste stabiele versies. Controleer de compatibiliteit in de officiële tabel Android Gradle Plugin compatibility.

Veelvoorkomende problemen bij het verhogen van compileSdk

Problemen bij het verhogen van compileSdkVersion vallen in drie categorieën: compilation errors, deprecated warnings en runtime incompatibilities. Compilation errors — methoden verwijderd uit de API en code compileert niet. Deprecated warnings — methoden gemarkeerd met @Deprecated, code compileert met waarschuwingen. Runtime incompatibilities — nieuwe API's zijn verplicht voor bepaalde functionaliteit en veroorzaken een fout bij onvoldoende API Level op het apparaat.

Het eerste veelvoorkomende probleem — "Cannot resolve symbol X". Dit betekent dat een klasse of methode is verwijderd uit de publieke API in de nieuwe SDK-versie. Oplossing: vind een alternatief op het nieuwe platform of gebruik de AndroidX-equivalent. Bijvoorbeeld, de klasse AsyncTaskLoader was deprecated in API 28 en verwijderd uit de publieke API in nieuwere versies. Alternatief — Kotlin Coroutines of WorkManager.

Het tweede probleem — wijziging van de methode-handtekening. In de nieuwe API-versie kan de methode het aantal of type parameters hebben gewijzigd. De Kotlin/Java-compiler geeft de fout "None of the following functions can be called with the arguments supplied". Oplossing: werk de methode-aanroep bij naar de nieuwe handtekening of voeg SDK_INT-controle toe met het aanroepen van de oude handtekening voor oude apparaten.

// Problemen oplossen bij het verhogen van compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Probleem: methode hasSystemFeature veranderde handtekening in API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nieuwe handtekening: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Oude handtekening: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Probleem: klasse verwijderd, gebruiken we AndroidX-equivalent
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // In plaats van android.app.FragmentManager (verwijderd) gebruiken we
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

De klasse CompileSdkProblemFixer lost veelvoorkomende problemen op: de gewijzigde handtekening van hasSystemFeature (hypothetische wijziging in API 36) wordt afgehandeld via SDK_INT-controle met het aanroepen van de juiste versie van de methode. De verwijderde klasse android.app.FragmentManager is vervangen door de AndroidX-equivalent. Voor oude aanroepen waar geen alternatief is, wordt @Suppress("DEPRECATION") gebruikt met een opmerking over de reden van behoud.