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 влияет на runtime-поведение системы на каждом устройстве, независимо от того, на какой версии 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 — исправьте ошибки: добавьте permissions, измените работу с файлами, обновите манифест.

Шаг 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 и ужесточена проверка existing типов. Все 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.