minSdkVersion: ما هو وكيفية اختيار الحد الأدنى لإصدار Android

ما هو minSdkVersion في Android؟

minSdkVersion هو معامل صحيح في build.gradle يحدد الحد الأدنى لمستوى API في Android لتثبيت التطبيق. إذا كان مستوى API للجهاز أقل من القيمة المحددة، يمنع PackageManager التثبيت، ويخفي Google Play Store التطبيق من نتائج البحث لذلك الجهاز. يتم كتابة minSdkVersion في AndroidManifest.xml أثناء البناء عبر الوسم <uses-sdk android:minSdkVersion> ويتم التحقق منه عند كل تثبيت.

قيمة minSdkVersion هي مفاضلة بين مدى الوصول إلى الجمهور والوصول إلى واجهات API جديدة. كلما انخفض minSdk، زاد عدد الأجهزة التي يمكنها تثبيت التطبيق، خاصة في المناطق النامية حيث تكون الهواتف الذكية القديمة التي تعمل بنظام Android شائعة. كلما ارتفع minSdk، قلّ كود التوافق العكسي المطلوب وتوفرت واجهات API حديثة أكثر بدون فحوصات وقت التشغيل. Android Jetpack ومكتبات AndroidX توفر إصدارات خلفية (backports) للعديد من واجهات API الجديدة على إصدارات Android القديمة، مما يسمح باختيار minSdk أقل دون فقدان الوظائف.

يؤثر minSdkVersion على جميع مراحل التطوير: التحليل الثابت (يستخدم lint قيمة minSdk للتحذيرات)، توافق التبعيات (قد تتطلب المكتبات minSdk خاصًا بها)، الاختبار (يلزم الاختبار على أجهزة ذات minSdk)، وGoogle Play Console (يتم حساب مدى الوصول إلى الجمهور بناءً على minSdk). تغيير minSdkVersion هو أحد أهم القرارات في إعداد المشروع، حيث أنه يؤثر على الكود والاختبارات وقاعدة المستخدمين.

أين يتم تحديد minSdkVersion

Build.gradle.kts (Kotlin DSL) هو المعيار الحديث في مشاريع Android. يتم تعيين معامل 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 لنكهات مختلفة
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

في المثال، minSdk = 26 يقابل Android 8.0 Oreo. هذه قيمة شائعة في 2026: تستبعد فقط ~15% من الأجهزة وفقًا لـ Distribution Dashboard في Android Studio. compileSdk = 36 يعطي الوصول إلى جميع واجهات API في Android 16، و targetSdk = 36 يتضمن تغييرات السلوك في الإصدار الأخير. لبنات التصحيح (debug)، يمكن خفض minSdk للاختبار على المحاكيات القديمة.

كيفية اختيار minSdkVersion: العوامل والاستراتيجية

اختيار minSdkVersion هو قرار استراتيجي يعتمد على تحليل الجمهور المستهدف ومتطلبات واجهات API والنظام البيئي للمكتبات. لا توجد قيمة واحدة صحيحة لجميع المشاريع. في 2026، يوصي Android Studio بـ minSdk = 26 (Android 8.0) كمستوى أساسي للمشاريع الجديدة، ولكن لتطبيقات B2B أو الحلول المؤسسية، قد تكون القيم الأقل أو الأعلى مقبولة.

عوامل اختيار minSdkVersion

العامل الأول هو Distribution Dashboard. يوفر Android Studio إحصائيات الأجهزة النشطة حسب مستوى API بناءً على بيانات Google Play، يتم تحديثها شهريًا. يجب أن يغطي minSdkVersion ما لا يقل عن 90-95% من الأجهزة النشطة في السوق المستهدف. للتطبيقات الدولية ذات الجمهور في أفريقيا وجنوب شرق آسيا، يجب خفض minSdk إلى 21 (Android 5.0) بسبب النسبة العالية من الأجهزة القديمة.

العامل الثاني هو متطلبات التبعيات. كل مكتبة لها minSdkVersion خاص بها محدد في بيانها (manifest). إذا كانت المكتبة تتطلب 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. ومع ذلك، يتم استخدام مزيج من الإصدارات الخلفية لـ 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: حلل تبعيات المشروع — قم بتشغيل البناء وأصلح تعارضات دمج البيان. الخطوة 4: قيم أي واجهات API من المستوى X تُستخدم فعليًا بدون إصدارات خلفية. الخطوة 5: عيّن minSdk كأقل قيمة تغطي 90%+ من الجمهور المستهدف ومتوافقة مع جميع التبعيات.

تغطية الأجهزة: توزيع مستويات API (2026)

توزيع الأجهزة حسب مستوى API هو مقياس ديناميكي يتغير كل ربع سنة. وفقًا لـ Distribution Dashboard في Android Studio حتى يونيو 2026، حوالي 85% من أجهزة Android النشطة تعمل على API 26 (Android 8.0) وما فوق، 72% على API 29 (Android 10) وما فوق، و55% على API 31 (Android 12) وما فوق. السوق الصيني له إحصائياته الخاصة بسبب عدم وجود Google Play Services على العديد من أجهزة Huawei.

أجهزة GMS (Google Mobile Services) يتم تحديثها بشكل أسرع: تصل حصة API 31+ عليها إلى 68% بفضل متطلبات Google Play الإلزامية للمصنعين. أجهزة non-GMS (Huawei وHonor وبعض العلامات التجارية الصينية) لها توزيع أقدم: حصة API 31+ عليها حوالي 35%. إذا كان تطبيقك موجهًا للسوق الدولي، اعتمد على الإحصائيات العالمية. إذا كان موجهًا للصين، ضع في اعتبارك قطاع non-GMS.

الاستنتاج: لتطبيق دولي، minSdk 26 يغطي 85% من الأجهزة بأقل تكاليف للتوافق العكسي. للتطبيقات ذات الجمهور في المناطق النامية، minSdk 21 (تغطية 97%) مبرر ولكنه يتطلب المزيد من الكود للعمل مع واجهات API القديمة. لتطبيقات المؤسسات مع أسطول أجهزة خاضع للتحكم، يمكنك تعيين minSdk 31 والتخلص تمامًا من كود الاحتياطي.

التوافق العكسي: AndroidX وlint و@RequiresApi

التوافق العكسي هو التحدي الرئيسي مع minSdkVersion المنخفض. يوفر AndroidX (المعروف سابقًا بـ Support Library) إصدارات خلفية لواجهات API الحديثة على إصدارات Android القديمة: AppCompatActivity لـ Material Design، FragmentManager، Loader، NotificationCompat، PreferenceFragmentCompat وعشرات المكونات الأخرى. استخدام مكافئات AndroidX بدلاً من واجهات API الأصلية هو الخطوة الأولى نحو التوافق.

lint (المحلل الثابت في Android Studio) يفحص الكود بحثًا عن استدعاءات واجهات API أعلى من minSdkVersion. إذا كانت طريقة ما موسومة بـ @RequiresApi بمستوى API أعلى من minSdk وتم استدعاؤها بدون فحص، يبرز lint خطأ. لقمع التحذير، استخدم الوسم @SuppressLint("NewApi") على الطريقة أو @RequiresApi(Build.VERSION_CODES.TIRAMISU) على الدالة بأكملها. فحوصات وقت التشغيل عبر Build.VERSION.SDK_INT هي الآلية الرئيسية لاستدعاء واجهات API جديدة بأمان على الأجهزة القديمة.

// مثال التوافق العكسي: PhotoPicker (API 34+) والاحتياطي
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 {
            // الاحتياطي: 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 مع احتياطي إلى GetContent. الطريقة usePhotoPickerOnly موسومة بـ @RequiresApi — lint لن يسمح باستدعائها بدون فحص. AppCompat من AndroidX يكيف تلقائيًا السمة والأجزاء (fragments) والرسوم المتحركة مع إصدار نظام التشغيل.

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، يضيف إصدارات خلفية
    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) يوفر إصدارات خلفية لـ Context وBundle وLocale وفئات نظام أخرى، مما يسمح للمكتبة بالحفاظ على minSdk منخفض.

الأخطاء الشائعة عند اختيار minSdkVersion

الأخطاء عند اختيار minSdk قد تكلف آلاف التثبيتات أو أسابيع من التطوير الإضافي. الخطأ الشائع الأول هو نسخ minSdk من قالب المشروع دون تحليل Distribution Dashboard. العديد من المطورين يتركون minSdk = 21 من قالب Android Studio، على الرغم من أن minSdk 26 سيكون كافيًا لجمهورهم وسيقلل من عدد فحوصات SDK_INT في الكود.

الخطأ الثاني هو minSdk مرتفع جدًا دون مراعاة السوق. إذا قمت بتعيين minSdk = 31 (Android 12) لتطبيق دولي، فإنك تفقد ~45% من الأجهزة. لشركة ناشئة أو تطبيق ذي جمهور واسع، هذه كارثة. تحقق دائمًا من Distribution Dashboard قبل رفع minSdk واستخدم اختبار A/B في Google Play Console إذا لم تكن متأكدًا.

الخطأ الثالث هو تجاهل minSkg للتبعيات. عند إضافة مكتبة جديدة، تحقق من minSdk الخاص بها في التوثيق أو ملف POM. Firebase ML Kit يتطلب minSdk 21، بعض المكتبات المخصصة للكاميرا تتطلب minSdk 29. إذا فشل دمج البيان في الإنتاج بسبب مكتبة جديدة، قد يستغرق الإصلاح أيامًا.

// مثال: فحص توافق 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 في اكتشاف الاستدعاءات غير المفحوصة، لكنه لا يمكنه ضمان تغطية كاملة للكود الديناميكي.