API Level: Was es ist, API-Versionen und targetSdk

Was ist API Level Android?

API Level Android ist eine ganzzahlige Kennung, die jeder öffentlichen Version der Android Framework API zugewiesen wird. Die erste Version Android 1.0 hatte 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. Jedes neue API Level kann neue Klassen, Methoden, Konstanten, Berechtigungen hinzufügen und das Verhalten bestehender ändern.

Das API Level erhöht sich nicht strikt um 1 mit jeder Version. Zum Beispiel hat Android 4.4W (Wear) API 20, während Android 5.0 API 21 hat. Lücken sind auf interne Iterationen und Wear OS-Geräte zurückzuführen. Für den Entwickler ist es wichtig, nicht den Versionsnamen (KitKat, Lollipop, Tiramisu) zu kennen, sondern dessen API Level — es wird im Code für Kompatibilitätsprüfungen verwendet.

Der Hauptzweck von API Level ist die Abwärtskompatibilität. Eine gegen API 34 kompilierte App kann auf Geräten mit API 34 und darunter ausgeführt werden (wenn sie keine neuen APIs ohne Prüfung verwendet). Android Runtime (ART) überprüft API-Aufrufe auf Systemebene und wendet Verhaltensänderungen in Abhängigkeit von targetSdkVersion der App an.

Wie Android API Level handhabt

Bei der Installation einer App überprüft PackageManager, ob das API Level des Geräts >= minSdkVersion aus AndroidManifest.xml ist. Wenn die Bedingung nicht erfüllt ist — wird die Installation mit der Meldung "App not installed" blockiert. Während der Laufzeit überwacht Android Runtime API-Aufrufe, die ein höheres API Level erfordern, und generiert NoSuchMethodError oder UnsatisfiedLinkError, wenn die Methode in der aktuellen Version nicht vorhanden ist.

minSdk, targetSdk, compileSdk: Unterschiede und Rolle der einzelnen Parameter

In der build.gradle-Datei (Module: app) gibt der Entwickler drei API Level-Parameter an: minSdkVersion, targetSdkVersion und compileSdkVersion. Sie zu verwechseln ist einer der häufigsten Fehler bei Android-Anfängern. Jeder Parameter ist für einen anderen Aspekt der Kompatibilität verantwortlich, und ihre Werte müssen konsistent sein.

minSdkVersion

minSdkVersion ist das minimale API Level, unter dem die App installiert und ausgeführt werden kann. Geräte mit einem API Level unter minSdk sehen die App nicht im Google Play Store und können sie nicht installieren. Der Wert wird basierend auf der Zielgruppe gewählt: minSdk 21 (Android 5.0) deckt 97% der Geräte ab, minSdk 26 (Android 8.0) — etwa 85%, minSdk 31 (Android 12) — etwa 55% (Daten aus Android Studio Distribution Dashboard, 2026). Je niedriger minSdk, desto größer die Abdeckung, aber desto mehr Abwärtskompatibilitätscode ist erforderlich.

targetSdkVersion

targetSdkVersion ist das API Level, mit dem die App getestet wurde. Android verwendet targetSdk, um Verhaltensänderungen anzuwenden: Wenn die App targetSdk 33 angibt, aktiviert das System alle in API 33 eingeführten Verhaltensänderungen. Wenn targetSdk 31 ist, wendet das System API 32-33 Änderungen nicht an und bewahrt die Kompatibilität mit altem Verhalten. Dies ist der wichtigste Parameter für die Sicherheit: Google Play verlangt targetSdk nicht älter als 1 Jahr ab dem aktuellen API Level.

compileSdkVersion

compileSdkVersion ist die Android SDK-Version, gegen die der Code kompiliert wird. Sie bestimmt, welche APIs zur Kompilierzeit verfügbar sind. compileSdk muss >= targetSdk sein und idealerweise dem neuesten stabilen API Level entsprechen. Eine Erhöhung von compileSdk beeinflusst nicht das Laufzeitverhalten — nur die Verfügbarkeit neuer APIs für den Compiler. Nach der Erhöhung von compileSdk muss der Code auf veraltete APIs und neue Berechtigungsanforderungen überprüft werden.

// build.gradle.kts — Beispiel für API Level-Konfiguration
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")
}

Im build.gradle.kts-Beispiel ist compileSdk = 36 (zum Zeitpunkt der Erstellung aktuellste), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 bietet Zugriff auf alle Android 16 APIs. targetSdk 36 aktiviert alle Android 16 Verhaltensänderungen. minSdk 26 deckt ~85% der Geräte ab. AndroidX Activity KTX und AppCompat bieten Abwärtskompatibilität für Fragmente und Themes.

AndroidManifest.xml

Die Parameter minSdk und targetSdk können auch in der AndroidManifest.xml angegeben werden, aber moderne Projekte verwenden build.gradle — Werte aus Gradle überschreiben das Manifest. Im Manifest kann es nützlich sein, für Bibliotheken und Module anzugeben, die keine Gradle-Build-Konfiguration verwenden.

Verhaltensänderungen: Wie targetSdk das App-Verhalten beeinflusst

Verhaltensänderungen sind Modifikationen der Arbeitsweise des Android-Systems, die nur auf Apps mit targetSdk >= einem bestimmten API Level angewendet werden. Jede neue Android-Version führt Verhaltensänderungen ein, die bestehende Apps beschädigen können, wenn sie nicht aktualisiert werden. Dies ist ein wichtiger Sicherheitsmechanismus von Android: Alte Apps funktionieren weiterhin wie zuvor, neue folgen den aktuellen Regeln.

Wichtige Verhaltensänderungen nach Version

Android 10 (API 29) — Scoped Storage: Apps mit targetSdk 29+ haben keinen direkten Zugriff auf das gemeinsame Dateisystem, nur über MediaStore, SAF oder eigenen Speicher. Android 11 (API 30) — Package Visibility: Paketfilter, Apps sehen nur installierte Pakete, mit denen sie interagieren. Android 12 (API 31) — Foreground Service Notification: Alle Vordergrunddienste müssen innerhalb von 10 Sekunden nach Start eine Benachrichtigung anzeigen. Android 13 (API 33) — POST_NOTIFICATIONS: Laufzeitberechtigung für Push-Benachrichtigungen. Android 14 (API 34) — Foreground Service Types: Obligatorische Deklaration des Vordergrunddiensttyps im Manifest.

// Behandlung von Android 13 (API 33) Verhaltensänderungen: 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) {
        // POST_NOTIFICATIONS-Berechtigung funktioniert nur mit API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Unter API 33 ist keine Berechtigung erforderlich
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Berechtigung bereits erteilt, Benachrichtigungen können gesendet werden
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Erklärung anzeigen, warum die Berechtigung benötigt wird
                activity.showRationale()
            }

            else -> {
                // Berechtigung anfordern
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Benachrichtigung erstellen und anzeigen
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Benachrichtigung")
            .setContentText("Neue Nachricht")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// requestPermissionLauncher in Activity registrieren
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Berechtigung erteilt
        }
    }

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

Beispiel für die Handhabung von POST_NOTIFICATIONS in Kotlin: Prüfen von Build.VERSION.SDK_INT >= TIRAMISU, Anfordern der Laufzeitberechtigung über ActivityResultContracts.RequestPermission, Verarbeiten des Ergebnisses in einem Callback. Ohne diese Berechtigung kann eine App mit targetSdk 33+ keine Push-Benachrichtigungen anzeigen. Unter API 33 ist keine Berechtigung erforderlich — der Prüfcode verhindert den Aufruf nicht verfügbarer APIs.

Scoped Storage (Android 10+)

Scoped Storage ist eine der bedeutendsten Verhaltensänderungen. Ab API 29 (targetSdk 29+) kann die App keinen direkten Dateizugriff auf die Verzeichnisse Pictures, Downloads, Music und Documents erhalten. Stattdessen wird MediaStore für Medien, SAF (Storage Access Framework) für beliebige Dateien und getExternalFilesDir() für eigenen Speicher verwendet. Ausnahme sind Apps mit der Berechtigung MANAGE_EXTERNAL_STORAGE, die eine Genehmigung von Google Play erfordert.

Google Play Anforderungen an API Level und targetSdk

Google Play legt verbindliche targetSdkVersion-Anforderungen für die Veröffentlichung von Apps fest. Seit August 2024 verlangt Google Play targetSdkVersion >= API 33 (Android 13). Jedes Jahr steigt die Schwelle: Neue Apps und Updates müssen targetSdk nicht älter als 1 Jahr ab dem aktuellen Haupt-API Level angeben. Ein Verstoß gegen die Anforderung führt zur Blockierung der Veröffentlichung und Entfernung der App aus dem Store.

Warum Google Play die Anforderungen verschärft

Der Hauptgrund ist die Sicherheit. Jedes neue Android API Level führt Verhaltensänderungen ein, die Angriffsvektoren schließen: Scoped Storage (API 29) verhindert Dateidiebstahl, POST_NOTIFICATIONS (API 33) schützt vor Spam-Benachrichtigungen, Foreground Service Types (API 34) schränkt versteckte Hintergrunddienste ein. Apps mit niedrigem targetSdk erhalten diesen Schutz nicht und werden zur Bedrohung für Benutzer. Google Play kann veraltete Apps auf modernen Geräten nicht zulassen.

Prüfung der Anforderungserfüllung

Die Google Play Console überprüft targetSdkVersion beim Hochladen von APK/AAB. Wenn targetSdk unter der Anforderung liegt — blockiert die Konsole die Veröffentlichung mit der Meldung: "Your app currently targets API level X and must target at least API level Y". Der Entwickler muss build.gradle aktualisieren, die App neu kompilieren, Verhaltensänderungen testen und erneut hochladen. Das AAB-Format wird für alle neuen Veröffentlichungen empfohlen (seit August 2021 verpflichtend).

API Level im Code prüfen: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT ist eine statische ganzzahlige Konstante, die das API Level des Geräts enthält, auf dem die App ausgeführt wird. Es ist das primäre Werkzeug für Laufzeit-Android-Versionsprüfungen. Build.VERSION_CODES enthält benannte Konstanten für jedes API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Der Vergleich via if (SDK_INT >= VERSION_CODES.TIRAMISU) ist das Standardmuster.

// Beispiele für API Level-Prüfungen in Android-Code
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Grundlegende API Level-Prüfung
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Adaptiver API-Aufruf mit Prüfung
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable ist nur mit API 26 (Android 8) verfügbar
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // Fallback für alte Geräte
    }

    // 3. Prüfung der POST_NOTIFICATIONS-Berechtigung (nur API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Auswahl des Bildanbieters nach API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ verwendet PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ verwendet Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (alle Versionen)
                "get_content"
            }
        }
    }

    // 5. Java-artige Prüfung via @TargetApi (für Abwärtskompatibilität)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Scoped Storage Verhalten hängt von targetSdk ab, nicht von SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Build-Informationen für Analysen
    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()}")
}

Die Klasse ApiLevelHelper demonstriert alle Hauptmuster der API Level-Prüfung: isAtLeastTiramisu mit SDK_INT >= VERSION_CODES, getAdaptiveIcon mit Fallback für alte Versionen, getImagePickerProvider with when-Mehrfachverzweigung, getDeviceApiInfo für Analysen. Die wichtigste Regel ist, keine neuen APIs ohne SDK_INT-Prüfung aufzurufen, sonst stürzt die App auf alten Geräten mit NoSuchMethodError ab.

ANT (Android New API) und lint

Android Studio enthält den statischen Analysator lint, der vor der Verwendung von APIs über minSdkVersion warnt. Wenn eine Methode ohne SDK_INT-Prüfung aufgerufen wird, markiert lint dies als Fehler: "Call requires API level 34 (current min is 26)". Lösungen: @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) zur Methode hinzufügen oder eine if-Prüfung von SDK_INT. @TargetApi ist eine veraltete Annotation, @RequiresApi wird empfohlen.

Tabelle der API Level und Android-Versionen

Die API Level-Tabelle ist ein Referenzwerkzeug für den Entwickler. Mit Kenntnis des API Level des Geräts kann die Android-Version und die verfügbaren Funktionen bestimmt werden. Die Tabelle listet alle wichtigen Android-Versionen von API Level 1 (2008) bis API Level 36 (2025) auf. Die Codenamen (Cupcake, Donut, Tiramisu, VanillaIceCream) werden intern bei Google und in VERSION_CODES verwendet.

Tabelle: Schwellen-API Level für Verhaltensänderungen

Die folgende Tabelle zeigt wichtige API Level, die Verhaltensänderungen einführen, die bei Erhöhung von targetSdk die Abwärtskompatibilität brechen: