targetSdkVersion: ключові поняття, behavioural changes та Google Play

Що таке targetSdkVersion в Android?

targetSdkVersion — цілочисельний параметр у build.gradle, який оголошує API Level, на якому застосунок тестувався. Система Android використовує цей параметр для вирішення, які behavioural changes застосовувати до застосунку під час виконання. Якщо targetSdkVersion = 33, Android застосовує всі behavioural changes, введені до API 33 включно, але не застосовує зміни API 34+. Якщо targetSdkVersion = 34 — застосовуються зміни до API 34, і так далі.

Ключова відмінність targetSdkVersion від minSdkVersion — механізм дії. minSdk перевіряється одноразово при встановленні та блокує встановлення, якщо умова не виконана. targetSdkVersion впливає на поведінку системи під час виконання на кожному пристрої, незалежно від того, на якій версії Android запущено застосунок. Той самий застосунок з targetSdk 31 поводитиметься по-різному на Android 13, 14 та 15, оскільки behavioural changes вище 31 вимкнені.

Механізм targetSdkVersion — це інструмент зворотної сумісності, вбудований в Android. Без нього кожне оновлення ОС ламало б тисячі старих застосунків. Google ввів цей механізм в Android 2.1 (API Level 7) і з тих пір використовує його як стандартний спосіб впровадження нових правил безпеки, конфіденційності та управління ресурсами без порушення роботи існуючих застосунків.

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

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36   // Протестовано під Android 16
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Перевірка поточного targetSdk у коді
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion містить targetSdk застосунку
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

У прикладі targetSdk = 36 включає всі behavioural changes Android 16. Код перевіряє targetSdkVersion через context.applicationInfo.targetSdkVersion — це дозволяє динамічно визначати, який режим сумісності увімкнено. Допоміжна функція корисна для бібліотек, які повинні адаптуватися під targetSdk викликаючого застосунку.

Behavioural Changes: як targetSdk впливає на застосунок

Behavioural changes — це модифікації поведінки системи Android, які застосовуються лише до застосунків з targetSdkVersion >= певного API Level. Кожен новий мажорний реліз Android вводить behavioural changes, і якщо застосунок не оновлює targetSdk, ці зміни не набувають чинності. Такий механізм дозволяє розробникам оновлювати застосунок у своєму темпі, а не синхронно з виходом нової версії ОС.

Scoped Storage (API 29) — одна з найзначніших behavioural changes. Застосунки з targetSdk 29+ не можуть отримувати прямий File-доступ до спільних директорій Pictures, Downloads, Music, Documents. Натомість використовується MediaStore для мультимедіа, SAF (Storage Access Framework) для довільних файлів та getExternalFilesDir() для власного сховища. Старі застосунки з targetSdk 28 і нижче продовжують працювати зі старим Full Storage Access, але це створює загрозу безпеці.

POST_NOTIFICATIONS (API 33) — runtime-дозвіл для надсилання сповіщень. Застосунки з targetSdk 33+ повинні запитувати дозвіл Manifest.permission.POST_NOTIFICATIONS у користувача через стандартний діалог. Якщо дозвіл не надано, NotificationManager.silent() не показує сповіщення користувачеві. На Android 13+ без цього дозволу push-сповіщення та локальні сповіщення просто не відображаються, що може суттєво знизити залученість користувачів.

Як перевірити поточний targetSdk

Значення targetSdkVersion можна отримати через ADB: команда adb shell dumpsys package com.example.myapp | grep targetSdk виводить targetSdk=34. У коді context.getApplicationInfo().targetSdkVersion повертає ціле число. Для аналітики корисно логувати targetSdk разом з android.os.Build.VERSION.SDK_INT, щоб розуміти, які behavioural changes фактично активні на кожному сеансі.

Вимоги Google Play до targetSdkVersion (2026)

Google Play встановлює обов'язкові вимоги до targetSdkVersion для всіх опублікованих застосунків. З серпня 2024 року мінімальний targetSdk = 33 (Android 13). З серпня 2025 року — targetSdk = 34. Очікується, що з серпня 2026 року Google вимагатиме targetSdk = 35 (Android 15). Нові застосунки та оновлення існуючих повинні відповідати цим вимогам, інакше консоль блокує публікацію. Це політика Google Play, а не обмеження Android Runtime: застосунок з targetSdk 34 може працювати на Android 16, але не може бути опублікований у Play Store.

Android App Bundle (AAB) — обов'язковий формат публікації з серпня 2021 року. APK більше не приймається в Google Play (виняток — застосунки з розміром > 150 MB та деякі legacy-проєкти). AAB-формат дозволяє Google генерувати оптимізовані APK для кожного API Level та щільності екрану, що знижує розмір завантаження на 15-30%. Для перевірки targetSdk Google Play аналізує AAB-маніфест і при невідповідності видає помилку із зазначенням мінімального необхідного значення.

Google Play Console перевіряє targetSdkVersion не тільки при завантаженні нового AAB, але й при оновленні існуючого застосунку. Якщо ваш застосунок має targetSdk 33, а Google підвищить мінімальний поріг до 34 — ви не зможете випустити жодного оновлення, доки не підвищите targetSdk. Для застосунків, які довго не оновлювалися, Google Play може автоматично зняти їх з публікації (unpublish).

Як оновлювати targetSdkVersion без помилок

Оновлення targetSdkVersion — не просто зміна числа в build.gradle. Кожна behavioural change може зламати існуючу функціональність, якщо не підготувати код заздалегідь. Рекомендується починати підготовку за 3-6 місяців до дедлайну Google Play, особливо якщо застосунок великий і використовує багато системних API.

Покроковий процес: Крок 1 — вивчіть behavioural changes для нового API Level у документації Android Developers (сторінка "Behavioural Changes by API Level"). Крок 2 — створіть гілку targetSdk-update та змініть targetSdk на нове значення. Крок 3 — запустіть застосунок на емуляторі або пристрої з новим API Level та перевірте кожну функціональність, пов'язану зі змінами. Крок 4 — виправте помилки: додайте дозволи, змініть роботу з файлами, оновіть маніфест.

Крок 5 — протестуйте на старих пристроях. Підвищення targetSdk не впливає на пристрої з API Level нижче нового targetSdk, але behavioural changes застосовуються на всіх пристроях з API Level >= targetSdk. Якщо ви підняли targetSdk з 33 до 34, то на пристроях з API 34+ включаться behavioural changes API 34. На пристроях з API 33 нічого не зміниться.

// Підготовка до 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 обмежує Advertising ID з API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — ідентифікатор недоступний, використовуємо MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Перевірка: які behavioural changes активні
    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")
        }
    }
}

Клас AdsManager показує підготовку до Privacy Sandbox (API 35). Advertising ID перестає бути доступним починаючи з API 35 при targetSdk 35+. Функція getActiveChanges демонструє правильний патерн перевірки behavioural changes: потрібно одночасно перевіряти і SDK_INT пристрою, і targetSdk застосунку. Тільки при збігу обох умов зміна дійсно активна.

Android 15 (API 35): ключові behavioural changes

Android 15 (API 35, Vanilla Ice Cream) вводить кілька критичних behavioural changes, які розробники повинні врахувати при оновленні targetSdk до 35. Перше — Privacy Sandbox for Android. Це ініціатива Google щодо заміни Advertising ID на більш приватні API: Topics API (інтереси користувача), Protected Audience (ремаркетинг) та Attribution Reporting (конверсії). З API 35 Advertising ID перестає бути стабільним ідентифікатором і може повертати нульове значення.

Друга зміна — Foreground Service Types (API 34, продовжено в API 35). Починаючи з API 34 кожен застосунок з targetSdk 34+ зобов'язаний вказати тип foreground-сервісу в маніфесті: dataSync, systemExempted, shortService, location, mediaPlayback та інші. Без цього система генерує ForegroundServiceTypeNotAllowedException. В API 35 додано новий тип health та посилено перевірку існуючих типів. Усі foreground-сервіси повинні бути переглянуті.

Третя зміна — обмеження на SCHEDULE_EXACT_ALARM. Починаючи з API 35 застосунки з targetSdk 35+ не можуть використовувати SCHEDULE_EXACT_ALARM без явного дозволу користувача. Система показує діалог, і користувач повинен схвалити точне планування. Для будильників і таймерів це означає додатковий крок в UX. Альтернатива — використовувати inexact-аларми з запасом у 10 хвилин.

// Android 15 (API 35): перевірка 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+: потрібен дозвіл користувача
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Нижче API 35 — точні аларми доступні без дозволу
        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 та обмеження алармів — дві найбільш критичні behavioural changes API 35. Для рекламних SDK знадобиться міграція на Topics API та Attribution Reporting. Для застосунків з будильниками та нагадуваннями — адаптація UX під діалог дозволу. Ігнорування цих змін призведе до крашу застосунку в runtime на Android 15 або до несправної рекламної монетизації.

Різниця між targetSdk та compileSdk

Різниця між targetSdkVersion та compileSdkVersion — одна з найчастіших тем плутанини серед Android-розробників. compileSdkVersion — це версія SDK, проти якої компілюється код. Вона визначає, які API доступні під час компіляції, але не впливає на runtime-поведінку. targetSdkVersion — це версія, під яку застосунок протестовано, вона визначає, які behavioural changes застосовуються в runtime. compileSdk може і повинна бути вищою або дорівнювати targetSdk.

Правило просте: compileSdk >= targetSdk >= minSdk. compileSdk зазвичай дорівнює останньому стабільному API Level (у 2026 році — 36). targetSdk повинен бути якомога вищим серед версій, під які ви провели тестування. minSdk повинен бути якомога нижчим для максимального охоплення. Підвищення compileSdk не потребує тестування behavioural changes — воно лише відкриває доступ до нових API для компілятора. Підвищення targetSdk потребує повного циклу тестування всіх behavioural changes.

На практиці: якщо ви хочете використовувати новий API з Android 16 (API 36), але behavioural changes API 36 ще не тестували, встановіть compileSdk = 36, targetSdk = 35. Код скомпілюється з новими API, але behavioural changes API 36 не будуть застосовуватися. Як тільки протестуєте всі зміни — підніміть targetSdk до 36.