targetSdkVersion: kluczowe pojęcia, behavioural changes i Google Play

Czym jest targetSdkVersion w Android?

targetSdkVersion — parametr całkowity w build.gradle, który deklaruje poziom API, na którym aplikacja była testowana. System Android używa tego parametru do decyzji, które behavioural changes zastosować do aplikacji podczas wykonania. Jeśli targetSdkVersion = 33, Android stosuje wszystkie behavioural changes wprowadzone do API 33 włącznie, ale nie stosuje zmian API 34+. Jeśli targetSdkVersion = 34 — stosowane są zmiany do API 34, i tak dalej.

Kluczowa różnica między targetSdkVersion a minSdkVersion — mechanizm działania. minSdk jest sprawdzany jednorazowo podczas instalacji i blokuje instalację, jeśli warunek nie jest spełniony. targetSdkVersion wpływa na zachowanie systemu w runtime na każdym urządzeniu, niezależnie od tego, na której wersji Androida aplikacja jest uruchomiona. Ta sama aplikacja z targetSdk 31 będzie działać inaczej na Android 13, 14 i 15, ponieważ behavioural changes powyżej 31 są wyłączone.

Mechanizm targetSdkVersion — to narzędzie wstecznej kompatybilności wbudowane w Androida. Bez niego każda aktualizacja systemu operacyjnego łamałaby tysiące starych aplikacji. Google wprowadził ten mechanizm w Android 2.1 (API Level 7) i od tego czasu używa go jako standardowego sposobu wprowadzania nowych zasad bezpieczeństwa, prywatności i zarządzania zasobami bez zakłócania działania istniejących aplikacji.

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

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

// Sprawdzenie bieżącego targetSdk w kodzie
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion zawiera targetSdk aplikacji
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

W przykładzie targetSdk = 36 włącza wszystkie behavioural changes Android 16. Kod sprawdza targetSdkVersion przez context.applicationInfo.targetSdkVersion — pozwala to dynamicznie określić, który tryb kompatybilności jest włączony. Funkcja pomocnicza jest przydatna dla bibliotek, które muszą dostosować się do targetSdk wywołującej aplikacji.

Behavioural Changes: jak targetSdk wpływa na aplikację

Behavioural changes — to modyfikacje zachowania systemu Android, które są stosowane tylko do aplikacji z targetSdkVersion >= określonego poziomu API. Każda nowa majorowa wersja Androida wprowadza behavioural changes, a jeśli aplikacja nie aktualizuje targetSdk, te zmiany nie wchodzą w życie. Taki mechanizm pozwala deweloperom aktualizować aplikację we własnym tempie, a nie synchronicznie z wydaniem nowej wersji systemu operacyjnego.

Scoped Storage (API 29) — jedna z najważniejszych behavioural changes. Aplikacje z targetSdk 29+ nie mogą uzyskać bezpośredniego dostępu File do wspólnych katalogów Pictures, Downloads, Music, Documents. Zamiast tego używany jest MediaStore dla multimediów, SAF (Storage Access Framework) dla dowolnych plików i getExternalFilesDir() dla własnego przechowywania. Stare aplikacje z targetSdk 28 i niższym nadal działają ze starym Full Storage Access, ale stwarza to zagrożenie bezpieczeństwa.

POST_NOTIFICATIONS (API 33) — uprawnienie runtime do wysyłania powiadomień. Aplikacje z targetSdk 33+ muszą żądać uprawnienia Manifest.permission.POST_NOTIFICATIONS od użytkownika poprzez standardowe okno dialogowe. Jeśli uprawnienie nie zostanie przyznane, NotificationManager.silent() nie pokazuje powiadomień użytkownikowi. Na Android 13+ bez tego uprawnienia push-powiadomienia i lokalne notyfikacje po prostu się nie wyświetlają, co może znacząco obniżyć zaangażowanie użytkowników.

Jak sprawdzić bieżący targetSdk

Wartość targetSdkVersion aplikacji można uzyskać przez ADB: polecenie adb shell dumpsys package com.example.myapp | grep targetSdk wyświetla targetSdk=34. W kodzie context.getApplicationInfo().targetSdkVersion zwraca liczbę całkowitą. Do analityki warto logować targetSdk razem z android.os.Build.VERSION.SDK_INT, aby rozumieć, które behavioural changes są faktycznie aktywne w każdej sesji.

Wymagania Google Play wobec targetSdkVersion (2026)

Google Play ustanawia obowiązkowe wymagania wobec targetSdkVersion dla wszystkich publikowanych aplikacji. Od sierpnia 2024 minimalny targetSdk = 33 (Android 13). Od sierpnia 2025 — targetSdk = 34. Oczekuje się, że od sierpnia 2026 Google będzie wymagać targetSdk = 35 (Android 15). Nowe aplikacje i aktualizacje istniejących muszą spełniać te wymagania, w przeciwnym razie konsola blokuje publikację. To polityka Google Play, a nie ograniczenie Android Runtime: aplikacja z targetSdk 34 może działać na Android 16, ale nie może być opublikowana w Play Store.

Android App Bundle (AAB) — obowiązkowy format publikacji od sierpnia 2021. APK nie jest już akceptowany w Google Play (wyjątek — aplikacje o rozmiarze > 150 MB i niektóre legacy-projekty). Format AAB pozwala Google generować zoptymalizowane APK dla każdego poziomu API i gęstości ekranu, co zmniejsza rozmiar pobierania o 15-30%. Do sprawdzenia targetSdk Google Play analizuje manifest AAB i w przypadku niezgodności wyświetla błąd z podaniem minimalnej wymaganej wartości.

Google Play Console sprawdza targetSdkVersion nie tylko przy przesyłaniu nowego AAB, ale także przy aktualizacji istniejącej aplikacji. Jeśli twoja aplikacja ma targetSdk 33, a Google podniesie minimalny próg do 34 — nie będziesz mógł wydać żadnej aktualizacji, dopóki nie podniesiesz targetSdk. Dla aplikacji, które długo nie były aktualizowane, Google Play może automatycznie usunąć je z publikacji (unpublish).

Jak aktualizować targetSdkVersion bez błędów

Aktualizacja targetSdkVersion — to nie tylko zmiana liczby w build.gradle. Każda behavioural change może złamać istniejącą funkcjonalność, jeśli kod nie zostanie wcześniej przygotowany. Zaleca się rozpoczęcie przygotowań na 3-6 miesięcy przed terminem Google Play, szczególnie jeśli aplikacja jest duża i używa wielu systemowych API.

Proces krok po kroku: Krok 1 — przestudiuj behavioural changes dla nowego poziomu API w dokumentacji Android Developers (strona "Behavioural Changes by API Level"). Krok 2 — utwórz gałąź targetSdk-update i zmień targetSdk na nową wartość. Krok 3 — uruchom aplikację na emulatorze lub urządzeniu z nowym poziomem API i sprawdź każdą funkcjonalność związaną ze zmianami. Krok 4 — napraw błędy: dodaj uprawnienia, zmień pracę z plikami, zaktualizuj manifest.

Krok 5 — przetestuj na starych urządzeniach. Podniesienie targetSdk nie wpływa na urządzenia z poziomem API niższym niż nowy targetSdk, ale behavioural changes są stosowane na wszystkich urządzeniach z API Level >= targetSdk. Jeśli podniosłeś targetSdk z 33 do 34, to na urządzeniach z API 34+ włączą się behavioural changes API 34. Na urządzeniach z API 33 nic się nie zmieni.

// Przygotowanie do 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 ogranicza Advertising ID od API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identyfikator niedostępny, używamy MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Sprawdzenie: które behavioural changes są aktywne
    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")
        }
    }
}

Klasa AdsManager pokazuje przygotowanie do Privacy Sandbox (API 35). Advertising ID przestaje być dostępny począwszy od API 35 przy targetSdk 35+. Funkcja getActiveChanges demonstruje prawidłowy wzorzec sprawdzania behavioural changes: należy jednocześnie sprawdzać SDK_INT urządzenia i targetSdk aplikacji. Tylko przy spełnieniu obu warunków zmiana jest faktycznie aktywna.

Android 15 (API 35): kluczowe behavioural changes

Android 15 (API 35, Vanilla Ice Cream) wprowadza kilka krytycznych behavioural changes, które deweloperzy muszą uwzględnić przy aktualizacji targetSdk do 35. Pierwsza — Privacy Sandbox for Android. To inicjatywa Google mająca na celu zastąpienie Advertising ID bardziej prywatnymi API: Topics API (zainteresowania użytkownika), Protected Audience (remarketing) i Attribution Reporting (konwersje). Od API 35 Advertising ID przestaje być stabilnym identyfikatorem i może zwracać wartość zerową.

Druga zmiana — Foreground Service Types (API 34, kontynuowane w API 35). Począwszy od API 34 każda aplikacja z targetSdk 34+ musi określić typ foreground-serwisu w manifeście: dataSync, systemExempted, shortService, location, mediaPlayback i inne. Bez tego system generuje ForegroundServiceTypeNotAllowedException. W API 35 dodano nowy typ health i zaostrzono sprawdzanie istniejących typów. Wszystkie foreground-serwisy muszą być przejrzane.

Trzecia zmiana — ograniczenie SCHEDULE_EXACT_ALARM. Począwszy od API 35 aplikacje z targetSdk 35+ nie mogą używać SCHEDULE_EXACT_ALARM bez wyraźnej zgody użytkownika. System wyświetla okno dialogowe, a użytkownik musi zatwierdzić dokładne planowanie. Dla budzików i timerów oznacza to dodatkowy krok w UX. Alternatywa — użycie inexact-alarmów z zapasem 10 minut.

// Android 15 (API 35): sprawdzenie 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+: wymagana zgoda użytkownika
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Poniżej API 35 — dokładne alarmy dostępne bez zgody
        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 i ograniczenie alarmów — dwie najbardziej krytyczne behavioural changes API 35. Dla SDK reklamowych wymagana będzie migracja na Topics API i Attribution Reporting. Dla aplikacji z budzikami i przypomnieniami — adaptacja UX pod okno dialogowe zgody. Ignorowanie tych zmian doprowadzi do crasha aplikacji w runtime na Android 15 lub do niedziałającej monetyzacji reklamowej.

Różnica między targetSdk a compileSdk

Różnica między targetSdkVersion a compileSdkVersion — jeden z najczęstszych tematów pomyłek wśród Android-deweloperów. compileSdkVersion — to wersja SDK, przeciwko której kompilowany jest kod. Określa ona, które API są dostępne podczas kompilacji, ale nie wpływa na zachowanie w runtime. targetSdkVersion — to wersja, pod którą aplikacja była testowana, określa ona, które behavioural changes są stosowane w runtime. compileSdk może i powinna być wyższa lub równa targetSdk.

Zasada jest prosta: compileSdk >= targetSdk >= minSdk. compileSdk zwykle równa się ostatniemu stabilnemu poziomowi API (w 2026 roku — 36). targetSdk powinien być jak najwyższy spośród wersji, pod które przeprowadzono testowanie. minSdk powinien być jak najniższy dla maksymalnego zasięgu. Podniesienie compileSdk nie wymaga testowania behavioural changes — otwiera jedynie dostęp do nowych API dla kompilatora. Podniesienie targetSdk wymaga pełnego cyklu testowania wszystkich behavioural changes.

W praktyce: jeśli chcesz używać nowego API z Android 16 (API 36), ale behavioural changes API 36 jeszcze nie testowałeś, ustaw compileSdk = 36, targetSdk = 35. Kod skompiluje się z nowymi API, ale behavioural changes API 36 nie będą stosowane. Gdy przetestujesz wszystkie zmiany — podnieś targetSdk do 36.