minSdkVersion: چیست و چگونه حداقل نسخه اندروید را انتخاب کنیم

minSdkVersion در اندروید چیست؟

minSdkVersion — یک پارامتر عدد صحیح در build.gradle است که حداقل سطح API اندروید را برای نصب برنامه تعیین می‌کند. اگر سطح API دستگاه کمتر از مقدار مشخص‌شده باشد، PackageManager نصب را مسدود می‌کند و Google Play Store برنامه را از نتایج جستجو برای چنین دستگاهی پنهان می‌کند. minSdkVersion در مرحله ساخت از طریق تگ <uses-sdk android:minSdkVersion> در AndroidManifest.xml نوشته می‌شود و در هر نصب بررسی می‌شود.

مقدار minSdkVersion یک مصالحه بین پوشش مخاطب و دسترسی به APIهای جدید است. هرچه minSdk کمتر باشد، دستگاه‌های بیشتری می‌توانند برنامه را نصب کنند، به ویژه در مناطق در حال توسعه که گوشی‌های هوشمند قدیمی اندروید محبوب هستند. هرچه minSdk بالاتر باشد، کد سازگاری معکوس کمتری نیاز است و APIهای مدرن بیشتری بدون بررسی‌های زمان اجرا در دسترس هستند. Android Jetpack و کتابخانه‌های AndroidX backport بسیاری از APIهای جدید را به نسخه‌های قدیمی اندروید ارائه می‌دهند که امکان انتخاب minSdk پایین‌تر را بدون از دست دادن قابلیت‌ها فراهم می‌کند.

minSdkVersion بر تمام مراحل توسعه تأثیر می‌گذارد: تحلیل استاتیک (lint از minSdk برای هشدارها استفاده می‌کند)، سازگاری وابستگی‌ها (کتابخانه‌ها ممکن است minSdk خود را نیاز داشته باشند)، تست (باید روی دستگاه‌های با minSdk تست کنید) و Google Play Console (پوشش مخاطب بر اساس minSdk محاسبه می‌شود). تغییر minSdkVersion یکی از مهم‌ترین تصمیمات در تنظیمات پروژه است، زیرا بر کد، تست‌ها و پایگاه کاربران تأثیر می‌گذارد.

minSdkVersion کجا مشخص می‌شود

Build.gradle.kts (Kotlin DSL) — استاندارد مدرن در پروژه‌های اندروید. پارامتر minSdk در بلوک defaultConfig در سطح ماژول تنظیم می‌شود. مقدار می‌تواند برای انواع ساخت و طعم‌های محصول مختلف بازنویسی شود که امکان تست روی APIهای پایین‌تر را بدون تغییر مقدار اصلی فراهم می‌کند.

// build.gradle.kts — تنظیمات پایه minSdk
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // بازنویسی minSdk برای flavorهای مختلف
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

در مثال minSdk = 26 معادل Android 8.0 Oreo است. این مقدار محبوبی در سال 2026 است: طبق Android Studio Distribution Dashboard فقط حدود 15% دستگاه‌ها را حذف می‌کند. compileSdk = 36 به تمام APIهای اندروید 16 دسترسی می‌دهد و targetSdk = 36 تغییرات رفتاری آخرین نسخه را فعال می‌کند. برای ساخت‌های debug می‌توان minSdk را برای تست روی شبیه‌سازهای قدیمی کاهش داد.

چگونه minSdkVersion را انتخاب کنیم: عوامل و استراتژی

انتخاب minSdkVersion — یک تصمیم استراتژیک مبتنی بر تحلیل مخاطب هدف، نیازمندی‌های API و اکوسیستم کتابخانه‌ها. یک مقدار صحیح واحد برای همه پروژه‌ها وجود ندارد. در سال 2026، Android Studio minSdk = 26 (اندروید 8.0) را به عنوان سطح پایه برای پروژه‌های جدید توصیه می‌کند، اما برای برنامه‌های B2B یا راه‌حل‌های شرکتی مقادیر پایین‌تر یا بالاتر قابل قبول است.

عوامل انتخاب minSdkVersion

عامل اول — Distribution Dashboard. Android Studio آمار دستگاه‌های فعال بر اساس سطح API را بر اساس داده‌های Google Play که ماهانه به‌روز می‌شوند ارائه می‌دهد. minSdkVersion باید حداقل 90-95% دستگاه‌های فعال بازار هدف را پوشش دهد. برای برنامه‌های بین‌المللی با مخاطب در آفریقا و آسیای جنوب شرقی، minSdk به دلیل سهم بالای دستگاه‌های قدیمی باید به 21 (اندروید 5.0) کاهش یابد.

عامل دوم — نیازمندی‌های وابستگی. هر کتابخانه minSdkVersion خود را دارد که در مانیفست آن مشخص شده است. اگر کتابخانه به minSdk 29 نیاز داشته باشد و برنامه minSdk 26 داشته باشد، ساخت با خطای manifest merger شکست می‌خورد. کتابخانه‌های مدرن Google Play Services minSdk 21، Firebase — minSdk 21، بیشتر کتابخانه‌های Jetpack — minSdk 21 یا 26، Compose BOM — minSdk 21 دارند. برای Compose حداقل آستانه — API 21 است.

عامل سوم — APIهای ضروری. اگر قابلیت کلیدی برنامه به API نیاز دارد که فقط از سطح خاصی در دسترس است (مثلاً PhotoPicker — API 34، Predicted Navigation — API 35)، این می‌تواند افزایش minSdk را توجیه کند. اما بیشتر از ترکیب backportهای AndroidX (Activity Result API، NotificationCompat) و بررسی‌های زمان اجرا استفاده می‌شود تا minSdk پایین حفظ شود.

استراتژی گام به گام انتخاب

گام 1: Android Studio را باز کنید، File → New Project و minSdk توصیه‌شده را در جادوگر ببینید. گام 2: Distribution Dashboard را در Android Studio بررسی کنید (View → Tool Windows → App Inspection → Distribution Dashboard). گام 3: وابستگی‌های پروژه را تحلیل کنید — ساخت را اجرا کرده و تعارضات manifest merger را رفع کنید. گام 4: ارزیابی کنید کدام APIهای سطح X واقعاً بدون backport استفاده می‌شوند. گام 5: minSdk را به عنوان حداقل مقداری که 90%+ مخاطب هدف را پوشش می‌دهد و با همه وابستگی‌ها سازگار است تنظیم کنید.

پوشش دستگاه‌ها: توزیع سطح API (2026)

توزیع دستگاه‌ها بر اساس سطح API — شاخصی پویا است که هر سه ماه تغییر می‌کند. طبق Android Studio Distribution Dashboard در ژوئن 2026، حدود 85% دستگاه‌های فعال اندروید روی API 26 (اندروید 8.0) و بالاتر، 72% روی API 29 (اندروید 10) و بالاتر، 55% روی API 31 (اندروید 12) و بالاتر کار می‌کنند. بازار چین آمار خاص خود را دارد زیرا بسیاری از دستگاه‌های Huawei فاقد Google Play Services هستند.

دستگاه‌های GMS (Google Mobile Services) سریع‌تر به‌روز می‌شوند: سهم API 31+ در آنها به دلیل الزامات اجباری Google Play برای تولیدکنندگان به 68% می‌رسد. دستگاه‌های غیر GMS (Huawei، Honor، برخی برندهای چینی) توزیع قدیمی‌تری دارند: سهم API 31+ در آنها حدود 35% است. اگر برنامه برای بازار بین‌المللی طراحی شده است، بر آمار جهانی تکیه کنید. اگر برای بازار چین — بخش غیر GMS را در نظر بگیرید.

نتیجه: برای برنامه بین‌المللی minSdk 26 با حداقل هزینه‌های سازگاری معکوس 85% دستگاه‌ها را پوشش می‌دهد. برای برنامه‌هایی با مخاطب در مناطق در حال توسعه، minSdk 21 (پوشش 97%) توجیه‌پذیر است اما برای کار با APIهای قدیمی به کد بیشتری نیاز دارد. برای برنامه‌های Enterprise با ناوگان کنترل‌شده دستگاه‌ها می‌توان minSdk 31 را تنظیم کرد و کاملاً از کد بازگشت خلاص شد.

سازگاری معکوس: AndroidX، lint و @RequiresApi

سازگاری معکوس — مشکل اصلی در minSdkVersion پایین. AndroidX ( قبلاً Support Library) backportهای APIهای مدرن را به نسخه‌های قدیمی اندروید ارائه می‌دهد: AppCompatActivity برای Material Design، FragmentManager، Loader، NotificationCompat، PreferenceFragmentCompat و ده‌ها مؤلفه دیگر. استفاده از معادل‌های AndroidX به جای APIهای بومی — اولین گام به سوی سازگاری است.

lint (تحلیل‌گر استاتیک Android Studio) کد را برای فراخوانی‌های API بالاتر از minSdkVersion اسکن می‌کند. اگر متد با @RequiresApi با سطح API بالاتر از minSdk مشخص شده باشد و بدون بررسی فراخوانی شود، lint خطا را برجسته می‌کند. برای سرکوب هشدار از annotion @SuppressLint("NewApi") روی متد یا @RequiresApi(Build.VERSION_CODES.TIRAMISU) روی کل تابع استفاده کنید. بررسی‌های زمان اجرا از طریق Build.VERSION.SDK_INT — مکانیسم اصلی فراخوانی ایمن APIهای جدید روی دستگاه‌های قدیمی است.

// مثال سازگاری معکوس: PhotoPicker (API 34+) و fallback
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — در هر سطح API کار می‌کند
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker فقط از API 34 در دسترس است
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // استفاده از PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (در همه نسخه‌ها کار می‌کند)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // این متد را نمی‌توان در API فراخوانی کرد < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

کلاس ImagePickerActivity سه سطح سازگاری معکوس را نشان می‌دهد. Activity Result API از AndroidX در تمام سطوح API کار می‌کند، بنابراین برای انتخاب تصویر پایه minSdk مهم نیست. PhotoPicker (ACTION_PICK_IMAGES) فقط از API 34 در دسترس است و تحت بررسی SDK_INT با fallback روی GetContent فراخوانی می‌شود. متد usePhotoPickerOnly با @RequiresApi مشخص شده است — lint اجازه فراخوانی آن را بدون بررسی نمی‌دهد. AppCompat از AndroidX به طور خودکار تم، فرگمنت‌ها و انیمیشن‌ها را با نسخه سیستم عامل تطبیق می‌دهد.

minSdkVersion در کتابخانه‌ها و ماژول‌ها

کتابخانه‌ها (AAR، JAR) نیز minSdkVersion مشخص‌شده در مانیفست خود را دارند. هنگام اتصال کتابخانه، Gradle سازگاری را بررسی می‌کند: اگر minSdk کتابخانه از minSdk برنامه بالاتر باشد، ساخت با خطا شکست می‌خورد. برای کتابخانه‌های عمومی توصیه می‌شود کمترین minSdk ممکن (21 برای بیشتر موارد) را مشخص کنید تا مصرف‌کنندگان محدود نشوند. اگر کتابخانه به API 29+ نیاز داشته باشد، حدود 28% کاربران بالقوه را از دست می‌دهد.

پروژه‌های چندماژوله می‌توانند minSdkVersion متفاوتی برای ماژول‌های مختلف داشته باشند. مثلاً ماژول :core:network می‌تواند minSdk 26 داشته باشد و ماژول :feature:camera — minSdk 29 (به دلیل CameraX با نیازمندی‌های خاص). Google Play نیاز دارد که minSdk ماژول اصلی :app کمتر یا مساوی minSdk همه ماژول‌های وابسته باشد. در عمل همه ماژول‌های یک برنامه معمولاً برای ساده‌سازی پشتیبانی minSdk یکسانی دارند.

// build.gradle.kts — ماژول کتابخانه با minSdk پایین
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // حداقل برای حداکثر پوشش
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21، backport اضافه می‌کند
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

ماژول کتابخانه با minSdk = 21 با 97% دستگاه‌ها سازگار است و مصرف‌کنندگان را محدود نمی‌کند. اگر کتابخانه از API بالاتر از 21 استفاده کند، توسعه‌دهنده باید بررسی‌های زمان اجرا اضافه کند یا @RequiresApi را روی متدهای مربوطه مشخص کند. AndroidX Core KTX (minSdk 21) backportهایی برای Context، Bundle، Locale و سایر کلاس‌های سیستمی فراهم می‌کند و به کتابخانه اجازه می‌دهد minSdk پایینی داشته باشد.

اشتباهات رایج در انتخاب minSdkVersion

اشتباهات در انتخاب minSdk می‌توانند هزاران نصب یا هفته‌ها توسعه اضافی هزینه داشته باشند. اولین اشتباه رایج — کپی کردن minSdk از الگوی پروژه بدون تحلیل Distribution Dashboard. بسیاری از توسعه‌دهندگان minSdk = 21 را از قالب Android Studio باقی می‌گذارند، در حالی که برای مخاطب آنها minSdk 26 کافی بود و تعداد بررسی‌های SDK_INT در کد را کاهش می‌داد.

دومین اشتباه — minSdk بیش از حد بالا بدون در نظر گرفتن بازار. اگر minSdk = 31 (اندروید 12) را برای یک برنامه بین‌المللی تنظیم کنید، حدود 45% دستگاه‌ها را از دست می‌دهید. برای یک استارتاپ یا برنامه با مخاطب انبوه این فاجعه است. همیشه قبل از افزایش minSdk Distribution Dashboard را بررسی کنید و اگر مطمئن نیستید از تست A/B در Google Play Console استفاده کنید.

سومین اشتباه — نادیده گرفتن minSdk وابستگی‌ها. هنگام اضافه کردن کتابخانه جدید، minSdk آن را در مستندات یا فایل POM بررسی کنید. Firebase ML Kit به minSdk 21 نیاز دارد، برخی کتابخانه‌های سفارشی دوربین به minSdk 29 نیاز دارند. اگر manifest merger در تولید به دلیل کتابخانه جدید از کار بیفتد، رفع آن ممکن است روزها طول بکشد.

// مثال: بررسی سازگاری API در زمان اجرا
fun checkFeatureAvailability(): Boolean {
    // خطای معمول — فراخوانی API بدون بررسی SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — از PhotoPicker استفاده می‌کنیم
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — از MediaStore استفاده می‌کنیم
            true
        }
        else -> {
            // API < 29 — از ACTION_GET_CONTENT استفاده می‌کنیم
            true
        }
    }
}

معماری صحیح بررسی‌های سطح API — when با بازه‌هایی که همه مقادیر ممکن از minSdk تا compileSdk را پوشش می‌دهند. قانون کلیدی: هر فراخوانی API سطح X باید با بررسی VERSION.SDK_INT برای همه دستگاه‌های با سطح API از minSdk تا X محافظت شود. lint به کشف فراخوانی‌های بررسی‌نشده کمک می‌کند، اما نمی‌تواند پوشش کامل را برای کد پویا تضمین کند.