مستوى API: ما هو، إصدارات 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 جديد قد يضيف فئات وطرق وثوابت وأذونات جديدة ويغير سلوك الموجودة.

لا يزيد مستوى API بشكل صارم بمقدار 1 مع كل إصدار. على سبيل المثال، Android 4.4W (Wear) لديه API 20، بينما Android 5.0 — API 21. ترتبط الفجوات بالتكرارات الداخلية وأجهزة Wear OS. من المهم للمطور معرفة ليس اسم الإصدار (KitKat، Lollipop، Tiramisu)، بل مستوى API الخاص به — فهو المستخدم في الكود لفحوصات التوافق.

الغرض الرئيسي من API Level هو التوافق العكسي. التطبيق المترجم ضد API 34 يمكن أن يعمل على أجهزة API 34 وما دون (إذا لم يستخدم واجهات برمجة تطبيقات جديدة دون تحقق). يتحقق Android Runtime (ART) من استدعاءات API على مستوى النظام ويطبق التغييرات السلوكية اعتمادًا على targetSdkVersion للتطبيق.

كيف يتعامل Android مع مستوى API

عند تثبيت التطبيق، يتحقق PackageManager من أن مستوى API للجهاز >= minSdkVersion من AndroidManifest.xml. إذا لم يتم استيفاء الشرط — يتم حظر التثبيت برسالة "App not installed". أثناء التشغيل، يراقب Android Runtime استدعاءات API التي تتطلب مستوى API أعلى ويولد NoSuchMethodError أو UnsatisfiedLinkError إذا كانت الطريقة غير موجودة في الإصدار الحالي.

minSdk و targetSdk و compileSdk: الاختلافات ودور كل معامل

في ملف build.gradle (Module: app)، يحدد المطور ثلاث معاملات لمستوى API: minSdkVersion و targetSdkVersion و compileSdkVersion. الخلط بينها هو أحد أكثر الأخطاء شيوعًا بين مطوري Android المبتدئين. كل معامل مسؤول عن جانب مختلف من التوافق، ويجب أن تكون قيمها متسقة.

minSdkVersion

minSdkVersion هو الحد الأدنى لمستوى API الذي يمكن عنده تثبيت التطبيق وتشغيله. الأجهزة ذات مستوى API أقل من 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 الذي تم اختبار التطبيق ضده. يستخدم Android targetSdk لتطبيق التغييرات السلوكية: إذا حدد التطبيق targetSdk 33، يقوم النظام بتمكين جميع التغييرات السلوكية المقدمة في API 33. إذا كان targetSdk 31، لا يطبق النظام تغييرات API 32-33، مع الحفاظ على التوافق مع السلوك القديم. هذا هو أهم معامل للأمان: يتطلب Google Play targetSdk لا يتجاوز عمره سنة واحدة من مستوى API الحالي.

compileSdkVersion

compileSdkVersion هو إصدار Android SDK الذي يتم ترجمة الكود ضده. يحدد واجهات برمجة التطبيقات المتاحة أثناء الترجمة. يجب أن يكون compileSdk >= targetSdk، ومن الأفضل أن يساوي أحدث مستوى API مستقر. زيادة compileSdk لا تؤثر على سلوك وقت التشغيل — فقط على توفر واجهات برمجة تطبيقات جديدة للمترجم. بعد رفع compileSdk، تحتاج إلى التحقق من الكود بحثًا عن واجهات برمجة تطبيقات مهملة ومتطلبات أذونات جديدة.

// 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 يتيح الوصول إلى جميع واجهات برمجة تطبيقات Android 16. targetSdk 36 يفعل جميع التغييرات السلوكية في Android 16. minSdk 26 يغطي ~85% من الأجهزة. توفر AndroidX Activity KTX و AppCompat التوافق العكسي للأجزاء (fragments) والسمات (themes).

AndroidManifest.xml

يمكن أيضًا تحديد معاملات minSdk و targetSdk في AndroidManifest.xml، لكن المشاريع الحديثة تستخدم build.gradle — القيم من Gradle تلغي البيان (manifest). في البيان، قد يكون من المفيد تحديد للمكتبات والوحدات التي لا تستخدم تكوين بناء Gradle.

التغييرات السلوكية: كيف يؤثر targetSdk على سلوك التطبيق

التغييرات السلوكية هي تعديلات في طريقة عمل نظام Android يتم تطبيقها فقط على التطبيقات ذات targetSdk >= مستوى API معين. كل إصدار جديد من 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، معالجة النتيجة في رد نداء. بدون هذا الإذن، لا يمكن للتطبيق ذو targetSdk 33+ إظهار الإشعارات الفورية. أسفل API 33 لا يتطلب الإذن — كود التحقق يمنع استدعاء واجهات برمجة تطبيقات غير متاحة.

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 و targetSdk

Google Play يضع متطلبات إلزامية لـ targetSdkVersion لنشر التطبيقات. منذ أغسطس 2024، يتطلب Google Play targetSdkVersion >= API 33 (Android 13). كل عام يرتفع الحد الأدنى: يجب أن تحدد التطبيقات والتحديثات الجديدة targetSdk لا يتجاوز عمره سنة واحدة من مستوى API الرئيسي الحالي. انتهاك المتطلب يؤدي إلى حظر النشر وإزالة التطبيق من المتجر.

لماذا يشدد Google Play المتطلبات

السبب الرئيسي هو الأمان. كل مستوى API جديد في Android يقدم تغييرات سلوكية تسد نواقل الهجوم: Scoped Storage (API 29) يمنع سرقة الملفات، POST_NOTIFICATIONS (API 33) يحمي من إشعارات البريد العشوائي، Foreground Service Types (API 34) يحد من الخدمات الخلفية المخفية. التطبيقات ذات targetSdk المنخفض لا تتلقى هذه الحماية وتصبح تهديدًا للمستخدمين. لا يمكن لـ Google Play السماح بتطبيقات قديمة على أجهزة حديثة.

التحقق من الامتثال للمتطلبات

يتحقق Google Play Console من targetSdkVersion عند رفع APK/AAB. إذا كان targetSdk أقل من المطلوب — تحظر لوحة التحكم النشر برسالة: "Your app currently targets API level X and must target at least API level Y". يجب على المطور تحديث build.gradle وإعادة ترجمة التطبيق واختبار التغييرات السلوكية وإعادة الرفع. يوصى بتنسيق AAB لجميع النشرات الجديدة (إلزامي منذ أغسطس 2021).

التحقق من مستوى API في الكود: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT هو ثابت عددي ثابت يحتوي على مستوى API للجهاز الذي يعمل عليه التطبيق. إنها الأداة الرئيسية لفحوصات إصدار Android في وقت التشغيل. Build.VERSION_CODES يحتوي على ثوابت مسماة لكل مستوى API: VERSION_CODES.TIRAMISU (33)، VERSION_CODES.UPSIDE_DOWN_CAKE (34)، VERSION_CODES.VANILLA_ICE_CREAM (35). المقارنة عبر if (SDK_INT >= VERSION_CODES.TIRAMISU) هي النمط القياسي.

// أمثلة على التحقق من مستوى API في كود 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
    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
    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: isAtLeastTiramisu مع SDK_INT >= VERSION_CODES، getAdaptiveIcon مع fallback للإصدارات القديمة، getImagePickerProvider مع when متعدد الفروع، getDeviceApiInfo للتحليلات. القاعدة الأساسية هي عدم استدعاء واجهات برمجة تطبيقات جديدة دون التحقق من SDK_INT، وإلا سيتعطل التطبيق مع NoSuchMethodError على الأجهزة القديمة.

ANT (Android New API) و lint

يتضمن Android Studio المحلل الثابت lint، الذي يحذر من استخدام واجهات برمجة تطبيقات أعلى من 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 وإصدارات Android

جدول مستوى API هو أداة مرجعية للمطور. بمعرفة مستوى API للجهاز، يمكن تحديد إصدار Android والميزات المتاحة. يسرد الجدول جميع الإصدارات الرئيسية لـ Android من API Level 1 (2008) إلى API Level 36 (2025). تستخدم الأسماء الرمزية (Cupcake، Donut، Tiramisu، VanillaIceCream) داخل Google وفي VERSION_CODES.

جدول: مستويات API الحدية للتغييرات السلوكية

يوضح الجدول التالي مستويات API الرئيسية التي تقدم تغييرات سلوكية تكسر التوافق العكسي عند رفع targetSdk: