targetSdkVersion: مفاهیم کلیدی، behavioural changes و Google Play

targetSdkVersion در Android چیست؟

targetSdkVersion — یک پارامتر عددی در build.gradle است که سطح API را که برنامه روی آن آزمایش شده اعلام می‌کند. سیستم 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 مشخصی اعمال می‌شوند. هر نسخه major جدید Android behavioural changes معرفی می‌کند و اگر برنامه targetSdk را به‌روزرسانی نکند، این تغییرات اعمال نمی‌شوند. چنین مکانیزمی به توسعه‌دهندگان اجازه می‌دهد برنامه را با سرعت خود به‌روزرسانی کنند، نه به طور همزمان با انتشار نسخه جدید سیستم‌عامل.

Scoped Storage (API 29) — یکی از مهمترین behavioural changes. برنامه‌های با targetSdk 29+ نمی‌توانند به دایرکتوری‌های عمومی Pictures، Downloads، Music، Documents دسترسی مستقیم File داشته باشند. به جای آن از 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+ بدون این مجوز، اعلان‌های فشاری و اعلان‌های محلی به سادگی نمایش داده نمی‌شوند که می‌تواند به طور قابل توجهی تعامل کاربران را کاهش دهد.

چگونه 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 و تراکم صفحه تولید کند که اندازه دانلود را 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 جدید را در مستندات Android Developers (صفحه "Behavioural Changes by API Level") مطالعه کنید. گام 2 — یک شاخه targetSdk-update ایجاد کنید و targetSdk را به مقدار جدید تغییر دهید. گام 3 — برنامه را روی شبیه‌ساز یا دستگاهی با سطح API جدید اجرا کنید و هر قابلیت مرتبط با تغییرات را بررسی کنید. گام 4 — خطاها را رفع کنید: مجوزها اضافه کنید، کار با فایل‌ها را تغییر دهید، مانیفست را به‌روزرسانی کنید.

گام 5 — روی دستگاه‌های قدیمی آزمایش کنید. افزایش targetSdk روی دستگاه‌هایی با سطح API پایین‌تر از 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 است. جایگزین — استفاده از alarmهای 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 — alarmهای دقیق بدون مجوز در دسترس هستند
        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 و محدودیت alarmها — دو 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 پایدار است (در 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 افزایش دهید.