targetSdkVersion: alapfogalmak, behavioural changes és Google Play

Mi az a targetSdkVersion Androidban?

targetSdkVersion — egy egész szám paraméter a build.gradle-ben, amely deklarálja azt az API szintet, amelyen az alkalmazást tesztelték. Az Android rendszer ezt a paramétert használja annak eldöntésére, hogy mely behavioural changes-eket alkalmazza az alkalmazásra a végrehajtás során. Ha a targetSdkVersion = 33, az Android alkalmazza az összes API 33-ig bezárólag bevezetett behavioural changes-t, de nem alkalmazza az API 34+ változásait. Ha a targetSdkVersion = 34 — az API 34-ig terjedő változások kerülnek alkalmazásra, és így tovább.

A legfontosabb különbség a targetSdkVersion és a minSdkVersion között — a hatásmechanizmus. A minSdk egyszer kerül ellenőrzésre a telepítéskor, és blokkolja a telepítést, ha a feltétel nem teljesül. A targetSdkVersion minden eszközön befolyásolja a rendszer futásidejű viselkedését, függetlenül attól, hogy az alkalmazás melyik Android verzión fut. Ugyanaz az alkalmazás targetSdk 31-gyel másképp fog viselkedni Android 13, 14 és 15 rendszeren, mert a 31 feletti behavioural changes ki vannak kapcsolva.

A targetSdkVersion mechanizmus — egy visszafelé kompatibilitási eszköz, amely az Androidba van beépítve. Nélküle minden operációsrendszer-frissítés több ezer régi alkalmazást tenne tönkre. A Google ezt a mechanizmust az Android 2.1-ben (API Level 7) vezette be, és azóta is szabványos módszerként használja új biztonsági, adatvédelmi és erőforrás-kezelési szabályok bevezetésére anélkül, hogy megzavarná a meglévő alkalmazások működését.

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

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

// A jelenlegi targetSdk ellenőrzése a kódban
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion tartalmazza az alkalmazás targetSdk-ját
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

A példában a targetSdk = 36 aktiválja az Android 16 összes behavioural changes-ét. A kód a context.applicationInfo.targetSdkVersion segítségével ellenőrzi a targetSdkVersion-t — ez lehetővé teszi annak dinamikus meghatározását, hogy melyik kompatibilitási mód van bekapcsolva. A segédfüggvény hasznos a könyvtárak számára, amelyeknek alkalmazkodniuk kell a hívó alkalmazás targetSdk-jéhez.

Behavioural Changes: hogyan befolyásolja a targetSdk az alkalmazást

Behavioural changes — az Android rendszer viselkedésének módosításai, amelyek csak a targetSdkVersion >= egy adott API szinttel rendelkező alkalmazásokra vonatkoznak. Minden új major Android kiadás behavioural changes-eket vezet be, és ha az alkalmazás nem frissíti a targetSdk-t, ezek a változások nem lépnek életbe. Egy ilyen mechanizmus lehetővé teszi a fejlesztők számára, hogy saját tempójukban frissítsék az alkalmazást, nem szinkronban az új OS verzió megjelenésével.

Scoped Storage (API 29) — az egyik legjelentősebb behavioural changes. A targetSdk 29+ alkalmazások nem kaphatnak közvetlen File hozzáférést a megosztott Pictures, Downloads, Music, Documents könyvtárakhoz. Ehelyett a MediaStore-t használják multimédiához, a SAF-ot (Storage Access Framework) tetszőleges fájlokhoz, és a getExternalFilesDir()-t saját tároláshoz. A targetSdk 28-as és alacsonyabb régi alkalmazások továbbra is a régi Full Storage Access-szel működnek, de ez biztonsági fenyegetést jelent.

POST_NOTIFICATIONS (API 33) — futásidejű engedély értesítések küldéséhez. A targetSdk 33+ alkalmazásoknak a Manifest.permission.POST_NOTIFICATIONS engedélyt kell kérniük a felhasználótól egy szabványos párbeszédablakon keresztül. Ha az engedélyt nem adják meg, a NotificationManager.silent() nem jeleníti meg az értesítéseket a felhasználónak. Android 13+ rendszeren ezen engedély nélkül a push-értesítések és a helyi értesítések egyszerűen nem jelennek meg, ami jelentősen csökkentheti a felhasználói elköteleződést.

Hogyan ellenőrizze a jelenlegi targetSdk-t

Az alkalmazás targetSdkVersion értéke ADB-n keresztül szerezhető meg: az adb shell dumpsys package com.example.myapp | grep targetSdk parancs megjeleníti a targetSdk=34 értéket. A kódban a context.getApplicationInfo().targetSdkVersion egy egész számot ad vissza. Analitikához érdemes naplózni a targetSdk-t az android.os.Build.VERSION.SDK_INT-vel együtt, hogy megértsük, mely behavioural changes-ek aktívak valójában az egyes munkamenetekben.

A Google Play targetSdkVersion követelményei (2026)

Google Play kötelező követelményeket támaszt a targetSdkVersion-nal szemben az összes publikált alkalmazás számára. 2024 augusztusától a minimális targetSdk = 33 (Android 13). 2025 augusztusától — targetSdk = 34. Várhatóan 2026 augusztusától a Google megköveteli a targetSdk = 35-öt (Android 15). Az új alkalmazásoknak és a meglévő alkalmazások frissítéseinek meg kell felelniük ezeknek a követelményeknek, különben a konzol blokkolja a közzétételt. Ez a Google Play irányelve, nem az Android Runtime korlátozása: egy targetSdk 34-es alkalmazás futhat Android 16-on, de nem publikálható a Play Store-ban.

Android App Bundle (AAB) — a kötelező közzétételi formátum 2021 augusztusa óta. Az APK-t már nem fogadják el a Google Play-ben (kivétel — a > 150 MB méretű alkalmazások és néhány legacy projekt). Az AAB formátum lehetővé teszi a Google számára, hogy optimalizált APK-kat generáljon minden API szinthez és képernyősűrűséghez, ami 15-30%-kal csökkenti a letöltési méretet. A targetSdk ellenőrzéséhez a Google Play elemzi az AAB manifestet, és meg nem felelés esetén hibát jelez a minimálisan szükséges érték megadásával.

A Google Play Console nemcsak új AAB feltöltésekor ellenőrzi a targetSdkVersion-t, hanem a meglévő alkalmazás frissítésekor is. Ha az alkalmazás targetSdk értéke 33, és a Google megemeli a minimális küszöböt 34-re — nem adhat ki egyetlen frissítést sem, amíg meg nem emeli a targetSdk-t. A hosszú ideje nem frissített alkalmazások esetében a Google Play automatikusan eltávolíthatja azokat a közzétételből (unpublish).

Hogyan frissítse a targetSdkVersion-t hibamentesen

A targetSdkVersion frissítése — nem csupán egy szám megváltoztatása a build.gradle-ben. Minden behavioural change tönkreteheti a meglévő funkcionalitást, ha a kódot nem készítik elő időben. Javasolt 3-6 hónappal a Google Play határideje előtt megkezdeni a felkészülést, különösen ha az alkalmazás nagy és sok rendszer API-t használ.

Lépésről lépésre: 1. lépés — tanulmányozza a behavioural changes-eket az új API szinthez az Android Developers dokumentációjában ("Behavioural Changes by API Level" oldal). 2. lépés — hozzon létre egy targetSdk-update ágat, és változtassa meg a targetSdk-t az új értékre. 3. lépés — futtassa az alkalmazást egy emulátoron vagy eszközön az új API szinttel, és ellenőrizze a változásokhoz kapcsolódó összes funkciót. 4. lépés — javítsa ki a hibákat: adjon hozzá engedélyeket, változtassa meg a fájlkezelést, frissítse a manifestet.

5. lépés — tesztelje régi eszközökön. A targetSdk emelése nem befolyásolja az új targetSdk-nél alacsonyabb API szintű eszközöket, de a behavioural changes-ek az összes API Level >= targetSdk eszközön alkalmazásra kerülnek. Ha a targetSdk-t 33-ról 34-re emelte, az API 34+ eszközökön bekapcsolnak a behavioural changes API 34 változásai. Az API 33 eszközökön semmi sem változik.

// Felkészülés a targetSdk 35-re: 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? {
        // A Privacy Sandbox korlátozza az Advertising ID-t API 35-től
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — az azonosító nem elérhető, MeasurementManager-t használunk
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Ellenőrzés: mely behavioural changes aktív
    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")
        }
    }
}

Az AdsManager osztály mutatja a Privacy Sandbox-ra (API 35) való felkészülést. Az Advertising ID az API 35-től kezdve targetSdk 35+ esetén már nem elérhető. A getActiveChanges függvény bemutatja a behavioural changes ellenőrzésének helyes mintáját: egyszerre kell ellenőrizni az eszköz SDK_INT-ját és az alkalmazás targetSdk-ját. Csak mindkét feltétel teljesülése esetén a változás ténylegesen aktív.

Android 15 (API 35): kulcsfontosságú behavioural changes

Android 15 (API 35, Vanilla Ice Cream) több kritikus behavioural changes-t vezet be, amelyeket a fejlesztőknek figyelembe kell venniük a targetSdk 35-re frissítésekor. Az első — Privacy Sandbox for Android. Ez a Google kezdeményezése az Advertising ID privátabb API-kkal való helyettesítésére: Topics API (felhasználói érdeklődési körök), Protected Audience (remarketing) és Attribution Reporting (konverziók). API 35-től kezdve az Advertising ID megszűnik stabil azonosító lenni, és nulla értéket adhat vissza.

A második változás — Foreground Service Types (API 34, folytatva API 35-ben). API 34-től kezdve minden targetSdk 34+ alkalmazásnak meg kell adnia a foreground szolgáltatás típusát a manifestben: dataSync, systemExempted, shortService, location, mediaPlayback és mások. Enélkül a rendszer ForegroundServiceTypeNotAllowedException-t generál. API 35-ben hozzáadták az új health típust, és szigorították a meglévő típusok ellenőrzését. Az összes foreground szolgáltatást felül kell vizsgálni.

A harmadik változás — a SCHEDULE_EXACT_ALARM korlátozása. API 35-től kezdve a targetSdk 35+ alkalmazások nem használhatják a SCHEDULE_EXACT_ALARM-ot a felhasználó kifejezett engedélye nélkül. A rendszer egy párbeszédablakot jelenít meg, és a felhasználónak jóvá kell hagynia a pontos ütemezést. Ébresztők és időzítők esetében ez egy további lépést jelent a UX-ben. Alternatíva — inexact riasztások használata 10 perces tartalékkal.

// Android 15 (API 35): SCHEDULE_EXACT_ALARM ellenőrzése
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+: felhasználói engedély szükséges
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // API 35 alatt — pontos riasztások engedély nélkül elérhetők
        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 és a riasztások korlátozása — az API 35 két legkritikusabb behavioural changes-e. A reklám SDK-k számára a Topics API-ra és az Attribution Reporting-ra való migráció szükséges. Az ébresztőket és emlékeztetőket tartalmazó alkalmazások számára — a UX adaptációja az engedélyezési párbeszédablak alá. E változtatások figyelmen kívül hagyása az alkalmazás összeomlásához vezet futásidőben Android 15 rendszeren, vagy a reklámmonetizáció működésképtelenségéhez.

Különbség a targetSdk és compileSdk között

A targetSdkVersion és a compileSdkVersion közötti különbség — az egyik leggyakoribb zavarforrás az Android-fejlesztők körében. A compileSdkVersion — az SDK verziója, amely ellen a kód fordítódik. Meghatározza, hogy mely API-k állnak rendelkezésre a fordítás során, de nem befolyásolja a futásidejű viselkedést. A targetSdkVersion — az a verzió, amely alatt az alkalmazást tesztelték, meghatározza, hogy mely behavioural changes-ek kerülnek alkalmazásra futásidőben. A compileSdk lehet és kell is, hogy magasabb vagy egyenlő legyen a targetSdk-nál.

A szabály egyszerű: compileSdk >= targetSdk >= minSdk. A compileSdk általában megegyezik az utolsó stabil API szinttel (2026-ban — 36). A targetSdk a lehető legmagasabb legyen a tesztelt verziók közül. A minSdk a lehető legalacsonyabb legyen a maximális lefedettség érdekében. A compileSdk emelése nem igényli a behavioural changes tesztelését — csak új API-khoz való hozzáférést nyit a fordító számára. A targetSdk emelése az összes behavioural changes teljes tesztciklusát igényli.

Gyakorlatban: ha új API-t szeretne használni az Android 16-ból (API 36), de az API 36 behavioural changes-eit még nem tesztelte, állítsa be a compileSdk = 36, targetSdk = 35 értékeket. A kód lefordul az új API-kkal, de az API 36 behavioural changes-ei nem kerülnek alkalmazásra. Amint letesztelte az összes változást — emelje a targetSdk-t 36-ra.