SDK Platform: چیست، نسخه‌ها و Android SDK Manager

SDK Platform چیست

SDK Platform — یک مؤلفه بنیادین Android SDK است که مجموعه کامل کتابخانه‌ها و ابزارها را برای توسعه برنامه‌های تحت یک نسخه خاص از اندروید فراهم می‌کند. هر پلتفرم با API Level شناسایی می‌شود — یک عدد صحیح که با انتشار نسخه‌های جدید سیستم عامل افزایش می‌یابد. مثلاً Android 13 با API Level 33، Android 14 با API Level 34 و Android 15 با API Level 35 مطابقت دارد.

برخلاف Android Studio (IDE)، SDK Platform شامل ویرایشگر کد یا دیباگر نیست. این یک لایه سیستمی است که به کامپایلر و ابزار ساخت متصل می‌شود. وقتی توسعه‌دهنده import android.app.Activity می‌نویسد، کامپایلر این کلاس را از android.jar مربوط به SDK Platform خاص می‌گیرد. بدون پلتفرم نصب‌شده با API Level مورد نیاز، کد کامپایل نخواهد شد.

Google برای هر نسخه پایدار اندروید یک SDK Platform جدید منتشر می‌کند. تاریخچه بیش از 35 API Level را شامل می‌شود — از Android 1.0 (API 1) تا Android 15 (API 35). هر پلتفرم با نسخه‌های قبلی سازگار است: کد نوشته شده برای API Level 21 روی API Level 35 کار خواهد کرد، اما برعکس نه.

چرا برای هر نسخه به SDK Platform جداگانه نیاز است

اندروید سریع رشد می‌کند: هر نسخه APIهای جدید اضافه می‌کند، رفتار APIهای موجود را تغییر می‌دهد و محدودیت‌هایی معرفی می‌کند. مثلاً Android 10 (API 29) Scoped Storage را معرفی کرد، Android 12 (API 31) — SplashScreen API، Android 14 (API 34) — پرچم‌های اجباری BroadcastReceiver. توسعه‌دهنده باید برنامه را علیه پلتفرم جاری بسازد تا از این قابلیت‌ها استفاده کند.

در عین حال برنامه می‌تواند روی نسخه‌های قدیمی سیستم عامل کار کند. برای این کار در Gradle پارامتر minSdk تعیین می‌شود — حداقل API Level که برنامه روی آن اجرا می‌شود. کد از بررسی نسخه و فراخوانی‌های شرطی API استفاده می‌کند. این رویکرد سازگاری را بدون از دست دادن قابلیت‌های جدید تضمین می‌کند.

ترکیب SDK Platform: اجزای اصلی

SDK Platform — یک فایل نیست، بلکه مجموعه‌ای از اجزاست که با هم کامپایل، ساخت و تست برنامه را فراهم می‌کنند. عنصر اصلی android.jar — بایگانی با کلاس‌های Android API موجود در این نسخه است. این فایل به کامپایلر Kotlin یا Java متصل می‌شود و مشخص می‌کند که چه کلاس‌ها، متدها و annotation‌هایی برای توسعه‌دهنده در دسترس است.

تصاویر سیستمی و شبیه‌ساز

هر SDK Platform شامل System Image — تصویر سیستم عامل برای شبیه‌ساز Android Virtual Device است. بدون تصویر مربوطه شبیه‌ساز نمی‌تواند دستگاه مجازی با API Level مورد نیاز را راه‌اندازی کند. System Images انواع مختلفی دارند: Google APIs (با سرویس‌های Google)، Google Play (با Play Store) و AOSP (اندروید خالص بدون سرویس‌های Google).

ابزارهای ساخت و دیباگ

SDK Platform شامل نسخه Build-Tools و Platform-Tools بهینه‌سازی شده برای این API Level است. Build-Tools شامل aapt2 (Android Asset Packaging Tool)، dx/d8 (کامپایلر Dalvik/ART) و ApkSigner است. Platform-Tools ADB (Android Debug Bridge)، fastboot و SQLite را فراهم می‌کند. این ابزارها مستقل از SDK Platform از طریق SDK Manager به‌روزرسانی می‌شوند.

منابع پلتفرم

هر پلتفرم شامل منابع استاندارد اندروید — تم‌های سیستمی، استایل‌ها، انیمیشن‌ها، رنگ‌ها و اندازه‌ها است. این منابع در هنگام کامپایل استفاده می‌شوند: اگر توسعه‌دهنده به @android:style/Theme.Material.Light ارجاع دهد، سازنده تعریف را از منابع SDK Platform می‌گیرد. این ظاهر یکپارچه اجزای سیستمی را در همه دستگاه‌ها تضمین می‌کند.

API Level و نسخه‌های SDK Platform

API Level — یک شناسه عددی صحیح از نسخه Android SDK است. هر انتشار اندروید با یک API Level مطابقت دارد که به صورت یکنواخت افزایش می‌یابد. توسعه‌دهنده API Level را در سه پارامتر کلیدی build.gradle مشخص می‌کند: compileSdk، minSdk و targetSdk. انتخاب این پارامترها تعیین می‌کند که کدام APIها در دسترس هستند و سیستم چگونه برنامه را پردازش می‌کند.

Google توصیه می‌کند minSdk را کمتر از آستانه توزیع فعلی نگه دارید — طبق Android Studio Distribution Dashboard (2026)، حدود 95٪ دستگاه‌ها روی Android 8.0 (API 26) و بالاتر کار می‌کنند. compileSdk باید آخرین نسخه پایدار باشد — این دسترسی به APIهای جدید را می‌دهد و به بررسی‌های lint اجازه می‌دهد متدهای منسوخ را تشخیص دهند.

تکامل API Level: تغییرات کلیدی

با هر API Level جدید Google تغییرات مهمی معرفی می‌کند. Android 6.0 (API 23) مجوزهای runtime را اضافه کرد — برنامه در حین اجرا مجوز می‌خواهد، نه در هنگام نصب. Android 8.0 (API 26) تکمیل خودکار فرم‌ها و کانال‌های اعلان را معرفی کرد. Android 12 (API 31) رویکرد به intentها را به طور اساسی تغییر داد — SplashScreen API و صادرات مؤلفه‌ها از طریق ویژگی exported ظاهر شد. Android 14 (API 34) مشخص کردن پرچم‌ها برای BroadcastReceiver را اجباری کرد و محدودیت‌های سختی برای foreground services معرفی کرد.

درک تاریخچه API Level به توسعه‌دهنده کمک می‌کند استراتژی سازگاری درستی انتخاب کند. اگر برنامه از compileSdk 35 استفاده می‌کند اما minSdk 26 است، کد می‌تواند متدهای API 35 را فقط پس از بررسی نسخه از طریق Build.VERSION.SDK_INT فراخوانی کند. این رویکرد version-gated development نامیده می‌شود و استاندارد صنعت است.

SDK Manager: نصب و تنظیمات

SDK Manager — ابزاری برای مدیریت کامپوننت‌های Android SDK: نصب SDK Platformهای جدید، به‌روزرسانی موجودها و حذف نسخه‌های منسوخ است. SDK Manager هم به عنوان رابط گرافیکی در Android Studio و هم خط فرمان از طریق sdkmanager در دسترس است. از طریق خط فرمان، SDK Manager برای استفاده در pipelineهای CI/CD که رابط گرافیکی ندارند مناسب است.

SDK Manager پلتفرم‌ها را در دایرکتوری Android SDK نصب می‌کند که به طور پیش‌فرض در $HOME/Android/Sdk در لینوکس و macOS و %LOCALAPPDATA%\Android\Sdk در ویندوز قرار دارد. در داخل دایرکتوری platforms پوشه‌هایی به شکل android-{API Level} وجود دارد که هر کدام شامل SDK Platform کامل است.

نصب SDK Platform از طریق sdkmanager

دستور sdkmanager شناسه بسته را با فرمت "platforms;android-{API}" می‌پذیرد. به عنوان مثال، برای نصب SDK Platform 35 دستور به این صورت است:

# نصب SDK Platform برای API Level 35
sdkmanager "platforms;android-35"

# نصب چند پلتفرم با یک دستور
sdkmanager "platforms;android-34" "platforms;android-33" "platforms;android-31"

# لیست پلتفرم‌های نصب شده
sdkmanager --list_installed | grep platforms

# حذف پلتفرم منسوخ
sdkmanager --uninstall "platforms;android-28"

نصب خودکار از طریق Gradle

پروژه‌های مدرن اندروید از Gradle Plugin استفاده می‌کنند که می‌تواند به طور خودکار SDK Platform را در اولین ساخت نصب کند. برای این کار باید compileSdk را در build.gradle مشخص کنید و دایرکتوری SDK را در تنظیمات محلی اضافه کنید. Android Studio نیز هنگام باز کردن پروژه نصب پلتفرم缺失 را پیشنهاد می‌دهد — کافی است دکمه "Install SDK Platform" را در پنجره همگام‌سازی Gradle کلیک کنید.

به‌روزرسانی منظم SDK Platform از طریق SDK Manager مهم است — همراه با پلتفرم Build-Tools و Platform-Tools نیز به‌روز می‌شوند که بر عملکرد ساخت و پایداری دیباگ تأثیر می‌گذارد. Google توصیه می‌کند هر 2–3 هفته یکبار به‌روزرسانی‌های SDK را بررسی کنید، به ویژه قبل از انتشار نسخه جدید برنامه در Google Play.

تنظیم تصویر سیستمی برای شبیه‌ساز

برای راه‌اندازی شبیه‌ساز با API Level مشخص باید System Image همان نسخه را نصب کنید. SDK Manager امکان بارگیری تصاویر معماری‌های مختلف (x86_64، arm64-v8a) و انواع (Google APIs، Google Play، AOSP) را فراهم می‌کند. پس از بارگیری تصویر، AVD Manager یک دستگاه مجازی بر اساس آن ایجاد می‌کند.

# نصب System Image با Google APIs برای API 35
sdkmanager "system-images;android-35;google_apis;x86_64"

# ایجاد AVD از طریق خط فرمان
avdmanager create avd -n pixel8 -k "system-images;android-35;google_apis;x86_64"

# لیست AVDهای ایجاد شده
avdmanager list avd

compileSdk، targetSdk و minSdk در Gradle

سه پارامتر در build.gradle نحوه کار برنامه با SDK Platform را تعیین می‌کنند. compileSdk — API Level که برای کامپایل استفاده می‌شود. این پارامتر مشخص می‌کند کدام کلاس‌های Android API در کد در دسترس هستند. compileSdk باید جدیدترین بین هر سه باشد و بر رفتار runtime تأثیر نمی‌گذارد — برنامه کامپایل می‌شود اما فقط از APIهایی که روی دستگاه هستند استفاده می‌کند.

minSdk — حداقل API Level که برنامه می‌تواند روی آن نصب شود. Google Play اجازه نصب برنامه روی دستگاهی با نسخه کمتر از minSdk را نمی‌دهد. این پارامتر آستانه سازگاری را تعیین می‌کند و بر پوشش مخاطب تأثیر می‌گذارد. هرچه minSdk پایین‌تر باشد، دستگاه‌های بیشتری پشتیبانی می‌شوند، اما APIهای جدید کمتری بدون بررسی می‌توان استفاده کرد.

targetSdk — API Level که برنامه روی آن تست شده است. سیستم اندروید از targetSdk برای اعمال تغییرات رفتاری استفاده می‌کند: اگر برنامه به API Level جدید به‌روز نشده باشد، سیستم حالت سازگاری برای نسخه‌های قدیمی را فعال می‌کند. Google Play targetSdk را کمتر از یک سطح مشخص نمی‌پذیرد — برای سال 2026 این API 34 است (Android 14).

مثال پیکربندی Gradle

android {
    compileSdk 35

    defaultConfig {
        applicationId "com.example.app"
        minSdk 26
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

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

// نسخه Android SDK باید از طریق SDK Manager نصب شود
// sdkmanager "platforms;android-35"

چگونه compileSdk، minSdk و targetSdk را انتخاب کنیم

استراتژی انتخاب به اهداف پروژه بستگی دارد. برای برنامه جدید: compileSdk — آخرین نسخه پایدار (35 در اوایل 2026)، minSdk — API 26 (Android 8.0، پوشش 95٪ دستگاه‌ها)، targetSdk — آخرین نسخه پایدار. برای به‌روزرسانی برنامه موجود: compileSdk را فوراً افزایش دهید، targetSdk — پس از تست همه تغییرات رفتاری، minSdk — فقط در صورت نیاز به رها کردن دستگاه‌های قدیمی.

Google الزام می‌کند که targetSdk ظرف یک سال پس از انتشار نسخه جدید اندروید به‌روز شود. برنامه‌هایی که این الزام را برآورده نمی‌کنند نمی‌توانند به‌روزرسانی‌ها را در Google Play منتشر کنند. برای پیگیری مهلت‌ها از تقویم رسمی به‌روزرسانی‌های Android OS استفاده کنید.

نمونه‌های کار با SDK Platform در کد

هنگام توسعه برای نسخه‌های مختلف اندروید باید در دسترس بودن API را در نظر گرفت. اگر برنامه از compileSdk 35 استفاده می‌کند اما روی دستگاهی با API 31 اجرا می‌شود، فراخوانی متدهای اضافه شده در API 34 منجر به NoSuchMethodError یا AbstractMethodError می‌شود. برای فراخوانی ایمن APIهای جدید از بررسی نسخه از طریق Build.VERSION.SDK_INT استفاده می‌شود.

بررسی API Level در runtime

class FeatureChecker {
    fun registerNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            // Notification channels از API 26 در دسترس هستند
            val channel = NotificationChannel(
                "updates",
                "به‌روزرسانی‌ها",
                NotificationManager.IMPORTANCE_DEFAULT
            )
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

استفاده از APIهای جدید با @RequiresApi

برای متدهایی که فقط در نسخه‌های خاصی فراخوانی می‌شوند، از annotation @RequiresApi استفاده کنید. این به بررسی‌های lint می‌گوید که متد ایمن است و هشدارها را غیرفعال می‌کند. در ترکیب با بررسی SDK_INT، annotation کد را تمیزتر و برای بازبینان قابل‌فهم‌تر می‌کند.

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun scheduleExactAlarm(manager: AlarmManager, time: Long) {
    // API 34: scheduleExact با پرچم SCHEDULE_EXACT_ALARM
    if (manager.canScheduleExactAlarms()) {
        manager.setExact(AlarmManager.RTC_WAKEUP, time, pendingIntent)
    } else {
        // درخواست مجوز SCHEDULE_EXACT_ALARM
        val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
        context.startActivity(intent)
    }
}

fun safeScheduleAlarm(context: Context, triggerTime: Long) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleExactAlarm(getAlarmManager(context), triggerTime)
    } else {
        // متد قدیمی setExact بدون بررسی مجوز
        getAlarmManager(context).setExact(AlarmManager.RTC_WAKEUP, triggerTime, pendingIntent)
    }
}

تعیین SDK Platform نصب شده

گاهی لازم است بدانیم چه نسخه‌ای از SDK Platform روی دستگاه توسعه‌دهنده یا در CI نصب شده است. این کار را می‌توان از طریق ADB یا به صورت برنامه‌نویسی در کد برنامه انجام داد. دانستن API Level دستگاه به تست رفتار وابسته به نسخه کمک می‌کند.

fun logDeviceInfo() {
    with (Build.VERSION) {
        Log.d("SDK_Demo", "SDK_INT: $SDK_INT")
        Log.d("SDK_Demo", "RELEASE: $RELEASE")
        Log.d("SDK_Demo", "CODENAME: $CODENAME")
        Log.d("SDK_Demo", "PREVIEW_SDK_INT: $PREVIEW_SDK_INT")
    }
    // خروجی: SDK_INT: 35, RELEASE: 15, CODENAME: REL
}