targetSdkVersion: kernconcepten, behavioural changes en Google Play

Wat is targetSdkVersion in Android?

targetSdkVersion — een integer parameter in build.gradle die het API-niveau declareert waarop de app is getest. Het Android-systeem gebruikt deze parameter om te beslissen welke behavioural changes op de app worden toegepast tijdens de uitvoering. Als targetSdkVersion = 33 is, past Android alle behavioural changes toe die tot en met API 33 zijn geïntroduceerd, maar past het wijzigingen van API 34+ niet toe. Als targetSdkVersion = 34 is — worden wijzigingen tot API 34 toegepast, enzovoort.

Het belangrijkste verschil tussen targetSdkVersion en minSdkVersion — het werkingsmechanisme. minSdk wordt eenmalig gecontroleerd bij installatie en blokkeert installatie als niet aan de voorwaarde wordt voldaan. targetSdkVersion beïnvloedt het runtime-gedrag van het systeem op elk apparaat, ongeacht op welke Android-versie de app wordt uitgevoerd. Dezelfde app met targetSdk 31 zal zich anders gedragen op Android 13, 14 en 15, omdat behavioural changes boven 31 zijn uitgeschakeld.

Het targetSdkVersion-mechanisme — is een hulpmiddel voor achterwaartse compatibiliteit dat in Android is ingebouwd. Zonder dit zou elke OS-update duizenden oude apps breken. Google introduceerde dit mechanisme in Android 2.1 (API Level 7) en gebruikt het sindsdien als de standaardmanier om nieuwe beveiligings-, privacy- en resourcebeheerregels in te voeren zonder de werking van bestaande apps te verstoren.

// build.gradle.kts — targetSdkVersion in defaultConfig
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

// Controle van huidige targetSdk in code
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion bevat targetSdk van de app
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

In het voorbeeld activeert targetSdk = 36 alle behavioural changes van Android 16. De code controleert targetSdkVersion via context.applicationInfo.targetSdkVersion — dit maakt het mogelijk dynamisch te bepalen welke compatibiliteitsmodus is ingeschakeld. De hulpfunctie is nuttig voor bibliotheken die zich moeten aanpassen aan de targetSdk van de aanroepende app.

Behavioural Changes: hoe targetSdk de app beïnvloedt

Behavioural changes — zijn wijzigingen in het gedrag van het Android-systeem die alleen worden toegepast op apps met targetSdkVersion >= een bepaald API-niveau. Elke nieuwe major Android-release introduceert behavioural changes, en als de app targetSdk niet update, worden deze wijzigingen niet van kracht. Een dergelijk mechanisme stelt ontwikkelaars in staat de app in hun eigen tempo te updaten, niet synchroon met de release van een nieuwe OS-versie.

Scoped Storage (API 29) — een van de belangrijkste behavioural changes. Apps met targetSdk 29+ kunnen geen directe File-toegang krijgen tot de gedeelde mappen Pictures, Downloads, Music, Documents. In plaats daarvan wordt MediaStore gebruikt voor multimedia, SAF (Storage Access Framework) voor willekeurige bestanden en getExternalFilesDir() voor eigen opslag. Oude apps met targetSdk 28 en lager blijven werken met de oude Full Storage Access, maar dit vormt een beveiligingsrisico.

POST_NOTIFICATIONS (API 33) — runtime-machtiging voor het verzenden van meldingen. Apps met targetSdk 33+ moeten de machtiging Manifest.permission.POST_NOTIFICATIONS van de gebruiker vragen via een standaard dialoogvenster. Als de machtiging niet wordt verleend, toont NotificationManager.silent() geen meldingen aan de gebruiker. Op Android 13+ zonder deze machtiging worden pushmeldingen en lokale notificaties gewoon niet weergegeven, wat de gebruikersbetrokkenheid aanzienlijk kan verminderen.

Hoe de huidige targetSdk te controleren

De waarde van targetSdkVersion van de app kan worden verkregen via ADB: het commando adb shell dumpsys package com.example.myapp | grep targetSdk toont targetSdk=34. In code retourneert context.getApplicationInfo().targetSdkVersion een geheel getal. Voor analyse is het nuttig om targetSdk samen met android.os.Build.VERSION.SDK_INT te loggen om te begrijpen welke behavioural changes daadwerkelijk actief zijn in elke sessie.

Google Play-vereisten voor targetSdkVersion (2026)

Google Play stelt verplichte vereisten aan targetSdkVersion voor alle gepubliceerde apps. Vanaf augustus 2024 is minimale targetSdk = 33 (Android 13). Vanaf augustus 2025 — targetSdk = 34. Naar verwachting zal Google vanaf augustus 2026 targetSdk = 35 (Android 15) vereisen. Nieuwe apps en updates van bestaande apps moeten aan deze vereisten voldoen, anders blokkeert de console publicatie. Dit is Google Play-beleid, geen Android Runtime-beperking: een app met targetSdk 34 kan op Android 16 draaien, maar kan niet worden gepubliceerd in de Play Store.

Android App Bundle (AAB) — het verplichte publicatieformaat sinds augustus 2021. APK wordt niet langer geaccepteerd in Google Play (uitzondering — apps met een grootte > 150 MB en sommige legacy-projecten). Het AAB-formaat stelt Google in staat geoptimaliseerde APK's te genereren voor elk API-niveau en schermdichtheid, waardoor de downloadgrootte met 15-30% afneemt. Om targetSdk te controleren, analyseert Google Play het AAB-manifest en geeft bij niet-naleving een foutmelding met de minimaal vereiste waarde.

Google Play Console controleert targetSdkVersion niet alleen bij het uploaden van een nieuwe AAB, maar ook bij het updaten van een bestaande app. Als uw app targetSdk 33 heeft en Google verhoogt de minimale drempel naar 34 — kunt u geen enkele update uitbrengen totdat u targetSdk verhoogt. Voor apps die lange tijd niet zijn bijgewerkt, kan Google Play ze automatisch uit de publicatie halen (unpublish).

Hoe targetSdkVersion foutloos te updaten

Het updaten van targetSdkVersion — is niet alleen een getal wijzigen in build.gradle. Elke behavioural change kan bestaande functionaliteit breken als de code niet van tevoren is voorbereid. Het wordt aanbevolen om 3-6 maanden voor de Google Play-deadline met de voorbereiding te beginnen, vooral als de app groot is en veel systeem-API's gebruikt.

Stapsgewijs proces: Stap 1 — bestudeer de behavioural changes voor het nieuwe API-niveau in de Android Developers-documentatie (pagina "Behavioural Changes by API Level"). Stap 2 — maak een branch targetSdk-update en wijzig targetSdk naar de nieuwe waarde. Stap 3 — start de app op een emulator of apparaat met het nieuwe API-niveau en controleer elke functionaliteit die verband houdt met de wijzigingen. Stap 4 — herstel fouten: voeg machtigingen toe, wijzig bestandsbewerkingen, update het manifest.

Stap 5 — test op oude apparaten. Het verhogen van targetSdk heeft geen invloed op apparaten met een API-niveau lager dan de nieuwe targetSdk, maar behavioural changes worden toegepast op alle apparaten met API Level >= targetSdk. Als u targetSdk van 33 naar 34 hebt verhoogd, worden op apparaten met API 34+ de behavioural changes van API 34 geactiveerd. Op apparaten met API 33 verandert er niets.

// Voorbereiding op targetSdk 35: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox beperkt Advertising ID vanaf API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identificatie niet beschikbaar, gebruiken we MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Controle: welke behavioural changes zijn actief
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

De klasse AdsManager toont de voorbereiding op Privacy Sandbox (API 35). Advertising ID is niet langer beschikbaar vanaf API 35 bij targetSdk 35+. De functie getActiveChanges demonstreert het juiste patroon voor het controleren van behavioural changes: zowel de SDK_INT van het apparaat als de targetSdk van de app moeten tegelijkertijd worden gecontroleerd. Alleen wanneer aan beide voorwaarden is voldaan, is de wijziging daadwerkelijk actief.

Android 15 (API 35): belangrijkste behavioural changes

Android 15 (API 35, Vanilla Ice Cream) introduceert verschillende kritieke behavioural changes die ontwikkelaars moeten meenemen bij het updaten van targetSdk naar 35. De eerste — Privacy Sandbox for Android. Dit is Google's initiatief om Advertising ID te vervangen door meer privacyvriendelijke API's: Topics API (gebruikersinteresses), Protected Audience (remarketing) en Attribution Reporting (conversies). Vanaf API 35 is Advertising ID geen stabiele identificatie meer en kan een nulwaarde retourneren.

De tweede wijziging — Foreground Service Types (API 34, voortgezet in API 35). Vanaf API 34 moet elke app met targetSdk 34+ het type foreground-service in het manifest specificeren: dataSync, systemExempted, shortService, location, mediaPlayback en andere. Zonder dit genereert het systeem ForegroundServiceTypeNotAllowedException. In API 35 is het nieuwe type health toegevoegd en is de controle van bestaande types aangescherpt. Alle foreground-services moeten worden herzien.

De derde wijziging — beperking van SCHEDULE_EXACT_ALARM. Vanaf API 35 kunnen apps met targetSdk 35+ SCHEDULE_EXACT_ALARM niet gebruiken zonder expliciete toestemming van de gebruiker. Het systeem toont een dialoogvenster en de gebruiker moet de exacte planning goedkeuren. Voor wekkers en timers betekent dit een extra stap in de UX. Alternatief — gebruik inexact-alarmen met een marge van 10 minuten.

// Android 15 (API 35): controle SCHEDULE_EXACT_ALARM
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: gebruikersmachtiging vereist
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Onder API 35 — exacte alarmen beschikbaar zonder machtiging
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox en de alarmbeperking — twee van de meest kritieke behavioural changes van API 35. Voor advertentie-SDK's zal migratie naar Topics API en Attribution Reporting nodig zijn. Voor apps met wekkers en herinneringen — UX-aanpassing aan het machtigingsdialoogvenster. Het negeren van deze wijzigingen leidt tot een crash van de app in runtime op Android 15 of tot niet-werkende advertentiemonetisatie.

Verschil tussen targetSdk en compileSdk

Het verschil tussen targetSdkVersion en compileSdkVersion — een van de meest verwarrende onderwerpen onder Android-ontwikkelaars. compileSdkVersion — is de SDK-versie waartegen de code wordt gecompileerd. Het bepaalt welke API's beschikbaar zijn tijdens de compilatie, maar heeft geen invloed op het runtime-gedrag. targetSdkVersion — is de versie waaronder de app is getest, het bepaalt welke behavioural changes in runtime worden toegepast. compileSdk kan en moet hoger of gelijk zijn aan targetSdk.

De regel is eenvoudig: compileSdk >= targetSdk >= minSdk. compileSdk is meestal gelijk aan het laatste stabiele API-niveau (in 2026 — 36). targetSdk moet zo hoog mogelijk zijn van de versies waaronder u hebt getest. minSdk moet zo laag mogelijk zijn voor maximale dekking. Het verhogen van compileSdk vereist geen testen van behavioural changes — het opent alleen toegang tot nieuwe API's voor de compiler. Het verhogen van targetSdk vereist een volledige testcyclus van alle behavioural changes.

In de praktijk: als u een nieuwe API uit Android 16 (API 36) wilt gebruiken, maar de behavioural changes van API 36 nog niet hebt getest, stel dan compileSdk = 36, targetSdk = 35 in. De code wordt gecompileerd met de nieuwe API's, maar de behavioural changes van API 36 worden niet toegepast. Zodra u alle wijzigingen hebt getest — verhoog targetSdk naar 36.