API Level: چیست، نسخه‌های API و targetSdk

API Level Android چیست؟

API Level Android یک شناسه عددی است که به هر انتشار عمومی Android Framework API اختصاص داده می‌شود. اولین انتشار Android 1.0 دارای API Level 1 بود، Android 1.5 — API Level 3، Android 2.2 — API Level 8، Android 4.0 — API Level 14، Android 8.0 — API Level 26، Android 12 — API Level 31، Android 14 — API Level 34، Android 15 — API Level 35، Android 16 (2025) — API Level 36. هر API Level جدید می‌تواند کلاس‌ها، روش‌ها، ثابت‌ها، مجوزهای جدید اضافه کند و رفتار موجودها را تغییر دهد.

API Level با هر انتشار به طور دقیق 1 افزایش نمی‌یابد. به عنوان مثال، Android 4.4W (Wear) دارای API 20 است، در حالی که Android 5.0 — API 21 است. شکاف‌ها مربوط به تکرارهای داخلی و دستگاه‌های Wear OS هستند. برای توسعه‌دهنده مهم است که نه نام نسخه (KitKat، Lollipop، Tiramisu)، بلکه API Level آن را بداند — این همان چیزی است که در کد برای بررسی‌های سازگاری استفاده می‌شود.

هدف اصلی API Level سازگاری به عقب است. برنامه‌ای که علیه API 34 کامپایل شده است می‌تواند بر روی دستگاه‌های با API 34 و پایین‌تر اجرا شود (اگر از APIهای جدید بدون بررسی استفاده نکند). Android Runtime (ART) فراخوانی‌های API را در سطح سیستم بررسی می‌کند و تغییرات رفتاری را بر اساس targetSdkVersion برنامه اعمال می‌کند.

چگونه Android API Level را مدیریت می‌کند

هنگام نصب برنامه، PackageManager بررسی می‌کند که API Level دستگاه >= minSdkVersion از AndroidManifest.xml است. اگر شرط برآورده نشود — نصب با پیام "App not installed" مسدود می‌شود. در طول اجرا، Android Runtime فراخوانی‌های API که نیاز به API Level بالاتری دارند را نظارت می‌کند و اگر روش در نسخه فعلی وجود نداشته باشد، NoSuchMethodError یا UnsatisfiedLinkError ایجاد می‌کند.

minSdk، targetSdk، compileSdk: تفاوت‌ها و نقش هر پارامتر

در فایل build.gradle (Module: app)، توسعه‌دهنده سه پارامتر API Level را مشخص می‌کند: minSdkVersion، targetSdkVersion و compileSdkVersion. اشتباه گرفتن آنها یکی از رایج‌ترین اشتباهات توسعه‌دهندگان مبتدی Android است. هر پارامتر مسئول جنبه متفاوتی از سازگاری است و مقادیر آنها باید سازگار باشند.

minSdkVersion

minSdkVersion حداقل API Level است که برنامه می‌تواند بر روی آن نصب و اجرا شود. دستگاه‌های با API Level پایین‌تر از minSdk برنامه را در Google Play نمی‌بینند و نمی‌توانند آن را نصب کنند. مقدار بر اساس مخاطب هدف انتخاب می‌شود: minSdk 21 (Android 5.0) 97٪ دستگاه‌ها را پوشش می‌دهد، minSdk 26 (Android 8.0) — حدود 85٪، minSdk 31 (Android 12) — حدود 55٪ (داده‌های Android Studio Distribution Dashboard، 2026). هرچه minSdk کمتر باشد، پوشش بیشتر است، اما کد سازگاری به عقب بیشتری نیاز است.

targetSdkVersion

targetSdkVersion API Level است که برنامه علیه آن آزمایش شده است. Android از targetSdk برای اعمال تغییرات رفتاری استفاده می‌کند: اگر برنامه targetSdk 33 را مشخص کند، سیستم تمام تغییرات رفتاری معرفی شده در API 33 را فعال می‌کند. اگر targetSdk 31 باشد، سیستم تغییرات API 32-33 را اعمال نمی‌کند و سازگاری با رفتار قدیمی را حفظ می‌کند. این مهمترین پارامتر برای امنیت است: Google Play نیاز دارد targetSdk بیش از 1 سال از API Level فعلی قدیمی‌تر نباشد.

compileSdkVersion

compileSdkVersion نسخه Android SDK است که کد علیه آن کامپایل می‌شود. تعیین می‌کند کدام APIها در زمان کامپایل در دسترس هستند. compileSdk باید >= targetSdk باشد و ایده‌آل این است که برابر با آخرین API Level پایدار باشد. افزایش compileSdk بر رفتار زمان اجرا تأثیر نمی‌گذارد — فقط بر در دسترس بودن APIهای جدید برای کامپایلر. پس از افزایش compileSdk، باید کد را برای APIهای منسوخ و نیازمندی‌های مجوز جدید بررسی کرد.

// build.gradle.kts — نمونه پیکربندی API Level
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

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

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

در مثال build.gradle.kts، compileSdk = 36 (آخرین در زمان نوشتن)، targetSdk = 36، minSdk = 26 (Android 8.0). compileSdk 36 به تمام APIهای Android 16 دسترسی می‌دهد. targetSdk 36 تمام تغییرات رفتاری Android 16 را فعال می‌کند. minSdk 26 حدود 85٪ دستگاه‌ها را پوشش می‌دهد. AndroidX Activity KTX و AppCompat سازگاری به عقب را برای fragmentها و تم‌ها فراهم می‌کنند.

AndroidManifest.xml

پارامترهای minSdk و targetSdk همچنین می‌توانند در AndroidManifest.xml مشخص شوند، اما پروژه‌های مدرن از build.gradle استفاده می‌کنند — مقادیر Gradle مانیفست را بازنویسی می‌کنند. در مانیفست، مشخص کردن برای کتابخانه‌ها و ماژول‌هایی که از پیکربندی build Gradle استفاده نمی‌کنند مفید است.

تغییرات رفتاری: targetSdk چگونه بر رفتار برنامه تأثیر می‌گذارد

تغییرات رفتاری اصلاحاتی در نحوه عملکرد سیستم Android هستند که فقط برای برنامه‌های با targetSdk >= یک API Level خاص اعمال می‌شوند. هر انتشار جدید Android تغییرات رفتاری را معرفی می‌کند که می‌تواند برنامه‌های موجود را در صورت عدم به‌روزرسانی خراب کند. این یک مکانیسم امنیتی کلیدی Android است: برنامه‌های قدیمی به کار خود ادامه می‌دهند، برنامه‌های جدید از قوانین فعلی پیروی می‌کنند.

تغییرات رفتاری اصلی بر اساس نسخه

Android 10 (API 29) — Scoped Storage: برنامه‌های با targetSdk 29+ به سیستم فایل مشترک دسترسی مستقیم ندارند، فقط از طریق MediaStore، SAF یا ذخیره‌سازی خود. Android 11 (API 30) — Package Visibility: فیلتر بسته، برنامه‌ها فقط بسته‌های نصب شده‌ای را می‌بینند که با آنها تعامل دارند. Android 12 (API 31) — Foreground Service Notification: همه سرویس‌های پیش‌زمینه موظف به نمایش اعلان در عرض 10 ثانیه پس از شروع هستند. Android 13 (API 33) — POST_NOTIFICATIONS: مجوز زمان اجرا برای اعلان‌های فشاری. Android 14 (API 34) — Foreground Service Types: اعلام اجباری نوع سرویس پیش‌زمینه در مانیفست.

// مدیریت تغییرات رفتاری Android 13 (API 33): POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // مجوز POST_NOTIFICATIONS فقط با API 33+ کار می‌کند
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // پایین‌تر از API 33 مجوز لازم نیست
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // مجوز قبلاً اعطا شده است، می‌توان اعلان‌ها را ارسال کرد
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // نمایش توضیح اینکه چرا مجوز لازم است
                activity.showRationale()
            }

            else -> {
                // درخواست مجوز
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // ایجاد و نمایش اعلان
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("اعلان")
            .setContentText("پیام جدید")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// ثبت requestPermissionLauncher در Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // مجوز دریافت شد
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

مثال مدیریت POST_NOTIFICATIONS در Kotlin: بررسی Build.VERSION.SDK_INT >= TIRAMISU، درخواست مجوز زمان اجرا از طریق ActivityResultContracts.RequestPermission، مدیریت نتیجه در callback. بدون این مجوز، برنامه با targetSdk 33+ نمی‌تواند اعلان‌های فشاری را نمایش دهد. پایین‌تر از API 33 مجوز لازم نیست — کد بررسی از فراخوانی APIهای در دسترس جلوگیری می‌کند.

Scoped Storage (Android 10+)

Scoped Storage یکی از مهم‌ترین تغییرات رفتاری است. از API 29 (targetSdk 29+) به بعد، برنامه نمی‌تواند به دایرکتوری‌های Pictures، Downloads، Music و Documents دسترسی مستقیم فایل داشته باشد. در عوض، MediaStore برای رسانه، SAF (Storage Access Framework) برای فایل‌های دلخواه و getExternalFilesDir() برای ذخیره‌سازی خود استفاده می‌شود. استثنا برنامه‌های با مجوز MANAGE_EXTERNAL_STORAGE هستند که نیاز به تأیید Google Play دارد.

نیازمندی‌های Google Play برای API Level و targetSdk

Google Play نیازمندی‌های اجباری targetSdkVersion را برای انتشار برنامه‌ها تعیین می‌کند. از آگوست 2024، Google Play نیاز دارد targetSdkVersion >= API 33 (Android 13). هر سال آستانه افزایش می‌یابد: برنامه‌ها و به‌روزرسانی‌های جدید باید targetSdk بیش از 1 سال از API Level اصلی فعلی قدیمی‌تر نباشد. نقض این نیازمندی منجر به مسدود شدن انتشار و حذف برنامه از فروشگاه می‌شود.

چرا Google Play نیازمندی‌ها را سخت‌تر می‌کند

دلیل اصلی امنیت است. هر API Level جدید Android تغییرات رفتاری را معرفی می‌کند که بردارهای حمله را می‌بندد: Scoped Storage (API 29) از سرقت فایل جلوگیری می‌کند، POST_NOTIFICATIONS (API 33) در برابر اعلان‌های اسپم محافظت می‌کند، Foreground Service Types (API 34) سرویس‌های پس‌زمینه پنهان را محدود می‌کند. برنامه‌های با targetSdk پایین این محافظت‌ها را دریافت نمی‌کنند و برای کاربران تهدید می‌شوند. Google Play نمی‌تواند برنامه‌های قدیمی را بر روی دستگاه‌های مدرن مجاز کند.

بررسی انطباق با نیازمندی‌ها

Google Play Console هنگام آپلود APK/AAB targetSdkVersion را بررسی می‌کند. اگر targetSdk پایین‌تر از حد مورد نیاز باشد — کنسول انتشار را با پیام مسدود می‌کند: "Your app currently targets API level X and must target at least API level Y". توسعه‌دهنده باید build.gradle را به‌روز کند، برنامه را دوباره کامپایل کند، تغییرات رفتاری را آزمایش کند و دوباره آپلود کند. فرمت AAB برای همه انتشارات جدید توصیه می‌شود (از آگوست 2021 اجباری است).

بررسی API Level در کد: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT یک ثابت عددی ایستا است که API Level دستگاه در حال اجرای برنامه را شامل می‌شود. این ابزار اصلی برای بررسی‌های نسخه Android در زمان اجرا است. Build.VERSION_CODES شامل ثابت‌های نام‌گذاری شده برای هر API Level است: VERSION_CODES.TIRAMISU (33)، VERSION_CODES.UPSIDE_DOWN_CAKE (34)، VERSION_CODES.VANILLA_ICE_CREAM (35). مقایسه از طریق if (SDK_INT >= VERSION_CODES.TIRAMISU) الگوی استاندارد است.

// نمونه‌های بررسی API Level در کد Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. بررسی پایه API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. فراخوانی API تطبیقی با بررسی
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable فقط با API 26 (Android 8) در دسترس است
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback برای دستگاه‌های قدیمی
    }

    // 3. بررسی مجوز POST_NOTIFICATIONS (فقط API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. انتخاب ارائه‌دهنده تصویر بر اساس API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ از PhotoPicker استفاده می‌کند
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ از Intent ACTION_OPEN_DOCUMENT استفاده می‌کند
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (همه نسخه‌ها)
                "get_content"
            }
        }
    }

    // 5. بررسی به سبک Java از طریق @TargetApi (برای سازگاری به عقب)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // رفتار Scoped Storage به targetSdk بستگی دارد، نه SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. اطلاعات ساخت برای تحلیل
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// آزمایش
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

کلاس ApiLevelHelper تمام الگوهای اصلی بررسی API Level را نشان می‌دهد: isAtLeastTiramisu با SDK_INT >= VERSION_CODES، getAdaptiveIcon با fallback برای نسخه‌های قدیمی، getImagePickerProvider با when چندشاخه، getDeviceApiInfo برای تحلیل. قانون کلیدی عدم فراخوانی APIهای جدید بدون بررسی SDK_INT است، در غیر این صورت برنامه در دستگاه‌های قدیمی با NoSuchMethodError خراب می‌شود.

ANT (Android New API) و lint

Android Studio شامل تحلیل‌گر ایستا lint است که درباره استفاده از API بالاتر از minSdkVersion هشدار می‌دهد. اگر یک روش بدون بررسی SDK_INT فراخوانی شود، lint آن را به عنوان خطا برجسته می‌کند: "Call requires API level 34 (current min is 26)". راه‌حل‌ها: افزودن @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) به روش یا بررسی if از SDK_INT. @TargetApi یک حاشیه‌نویس منسوخ است، @RequiresApi توصیه می‌شود.

جدول تطابق API Level و نسخه‌های Android

جدول API Level یک ابزار مرجع برای توسعه‌دهنده است. با دانستن API Level دستگاه، می‌توان نسخه Android و ویژگی‌های موجود را تعیین کرد. جدول تمام انتشارات اصلی Android را از API Level 1 (2008) تا API Level 36 (2025) فهرست می‌کند. نام‌های رمز (Cupcake، Donut، Tiramisu، VanillaIceCream) در داخل Google و در VERSION_CODES استفاده می‌شوند.

جدول: API Level آستانه برای تغییرات رفتاری

جدول زیر API Levelهای کلیدی را نشان می‌دهد که تغییرات رفتاری شکستن سازگاری به عقب را هنگام افزایش targetSdk معرفی می‌کنند: