targetSdkVersion: المفاهيم الأساسية، التغييرات السلوكية وGoogle Play

ما هو targetSdkVersion في Android؟

targetSdkVersion هو معامل عددي في build.gradle يعلن عن مستوى API الذي تم اختبار التطبيق ضده. يستخدم نظام Android هذا المعامل لتحديد أي التغييرات السلوكية يجب تطبيقها على التطبيق أثناء التشغيل. إذا كان targetSdkVersion = 33، يقوم Android بتطبيق جميع التغييرات السلوكية المقدمة حتى API 33 شاملاً، لكنه لا يطبق تغييرات API 34+. إذا كان targetSdkVersion = 34 — يتم تطبيق التغييرات حتى API 34، وهكذا.

الفرق الرئيسي بين targetSdkVersion وminSdkVersion هو آلية العمل. يتم التحقق من minSdk مرة واحدة أثناء التثبيت ويمنع التثبيت إذا لم يتم استيفاء الشرط. targetSdkVersion يؤثر على سلوك وقت التشغيل للنظام على كل جهاز، بغض النظر عن إصدار Android الذي يعمل عليه التطبيق. نفس التطبيق مع targetSdk 31 سيتصرف بشكل مختلف على Android 13 و14 و15، لأن التغييرات السلوكية فوق 31 معطلة.

آلية targetSdkVersion هي أداة توافق عكسي مدمجة في Android. بدونها، كل تحديث لنظام التشغيل سيكسر آلاف التطبيقات القديمة. قدم Google هذه الآلية في Android 2.1 (API Level 7) ومنذ ذلك الحين يستخدمها كطريقة قياسية لإدخال قواعد جديدة للأمان والخصوصية وإدارة الموارد دون كسر التطبيقات الحالية.

// build.gradle.kts — targetSdkVersion في defaultConfig
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36   // تم الاختبار على Android 16
        versionCode = 1
        versionName = "1.0.0"
    }
}

// التحقق من targetSdk الحالي في الكود
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion يحتوي على targetSdk للتطبيق
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

في المثال، targetSdk = 36 يفعل جميع التغييرات السلوكية لـ Android 16. يتحقق الكود من targetSdkVersion عبر context.applicationInfo.targetSdkVersion — وهذا يسمح بتحديد وضع التوافق النشط ديناميكيًا. الدالة المساعدة مفيدة للمكتبات التي تحتاج إلى التكيف مع targetSdk للتطبيق المستدعي.

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

التغييرات السلوكية هي تعديلات في سلوك نظام Android يتم تطبيقها فقط على التطبيقات التي targetSdkVersion >= مستوى API معين. كل إصدار رئيسي جديد من Android يقدم تغييرات سلوكية، وإذا لم يقم التطبيق بتحديث targetSdk، فإن هذه التغييرات لا تدخل حيز التنفيذ. تسمح هذه الآلية للمطورين بتحديث تطبيقهم بالسرعة التي تناسبهم، بدلاً من التزامن مع إصدار نظام تشغيل جديد.

Scoped Storage (API 29) هو واحد من أهم التغييرات السلوكية. التطبيقات ذات targetSdk 29+ لا يمكنها الوصول المباشر بالملفات إلى الدلائل المشتركة Pictures وDownloads وMusic وDocuments. بدلاً من ذلك، يتم استخدام MediaStore للوسائط المتعددة وSAF (Storage Access Framework) للملفات العشوائية وgetExternalFilesDir() للتخزين الخاص. التطبيقات القديمة ذات targetSdk 28 وما دون تستمر في العمل مع Full Storage Access القديم، لكن هذا يشكل خطرًا أمنيًا.

POST_NOTIFICATIONS (API 33) هو إذن وقت تشغيل لإرسال الإشعارات. التطبيقات ذات targetSdk 33+ يجب أن تطلب الإذن Manifest.permission.POST_NOTIFICATIONS من المستخدم عبر الحوار القياسي. إذا لم يتم منح الإذن، فإن NotificationManager.silent() لا يعرض الإشعارات للمستخدم. على Android 13+ بدون هذا الإذن، إشعارات الدفع والإشعارات المحلية ببساطة لا تظهر، مما قد يقلل بشكل كبير من تفاعل المستخدم.

كيفية التحقق من targetSdk الحالي

يمكن الحصول على قيمة targetSdkVersion عبر ADB: الأمر adb shell dumpsys package com.example.myapp | grep targetSdk يظهر targetSdk=34. في الكود، context.getApplicationInfo().targetSdkVersion يُرجع عددًا صحيحًا. للتحليلات، من المفيد تسجيل targetSdk مع android.os.Build.VERSION.SDK_INT لفهم أي التغييرات السلوكية نشطة فعليًا في كل جلسة.

متطلبات Google Play لـ targetSdkVersion (2026)

Google Play يضع متطلبات إلزامية لـ targetSdkVersion لجميع التطبيقات المنشورة. منذ أغسطس 2024، الحد الأدنى targetSdk = 33 (Android 13). منذ أغسطس 2025، targetSdk = 34. من المتوقع أنه اعتبارًا من أغسطس 2026، سيطلب Google targetSdk = 35 (Android 15). يجب على التطبيقات الجديدة وتحديثات التطبيقات الحالية الامتثال لهذه المتطلبات، وإلا ستحظر وحدة التحكم النشر. هذه سياسة Google Play، وليست قيدًا على Android Runtime: تطبيق مع targetSdk 34 يمكنه العمل على Android 16، لكن لا يمكن نشره في Play Store.

Android App Bundle (AAB) هو تنسيق النشر الإلزامي منذ أغسطس 2021. لم يعد APK مقبولاً في Google Play (باستثناء التطبيقات الأكبر من 150 ميغابايت وبعض المشاريع القديمة). يتيح تنسيق AAB لـ Google إنشاء APK محسّنة لكل مستوى API وكثافة شاشة، مما يقلل حجم التنزيل بنسبة 15-30%. للتحقق من targetSdk، يحلل Google Play بيان AAB ويصدر خطأً مع الحد الأدنى المطلوب إذا لم يكن متوافقًا.

Google Play Console تتحقق من targetSdkVersion ليس فقط عند رفع AAB جديد، ولكن أيضًا عند تحديث تطبيق موجود. إذا كان تطبيقك لديه targetSdk 33 وقام Google برفع الحد الأدنى إلى 34 — لن تتمكن من إصدار أي تحديثات حتى ترفع targetSdk. بالنسبة للتطبيقات التي لم يتم تحديثها لفترة طويلة، قد يقوم Google Play بإزالتها تلقائيًا من النشر (unpublish).

كيفية تحديث targetSdkVersion بدون أخطاء

تحديث targetSdkVersion ليس مجرد تغيير رقم في build.gradle. كل تغيير سلوكي يمكن أن يكسر الوظائف الحالية إذا لم يتم تحضير الكود مسبقًا. يوصى ببدء التحضير قبل 3-6 أشهر من الموعد النهائي لـ Google Play، خاصة إذا كان التطبيق كبيرًا ويستخدم العديد من API النظام.

عملية خطوة بخطوة: الخطوة 1 — ادرس التغييرات السلوكية لمستوى API الجديد في توثيق Android Developers (صفحة "Behavioural Changes by API Level"). الخطوة 2 — أنشئ فرع targetSdk-update وغيّر targetSdk إلى القيمة الجديدة. الخطوة 3 — شغّل التطبيق على محاكٍ أو جهاز بمستوى API الجديد وتحقق من كل وظيفة متعلقة بالتغييرات. الخطوة 4 — أصلح الأخطاء: أضف الأذونات، غيّر التعامل مع الملفات، حدّث البيان.

الخطوة 5 — اختبر على الأجهزة القديمة. رفع targetSdk لا يؤثر على الأجهزة ذات مستوى API أقل من targetSdk الجديد، لكن التغييرات السلوكية تُطبق على جميع الأجهزة ذات API Level >= targetSdk. إذا رفعت targetSdk من 33 إلى 34، فستُفعّل التغييرات السلوكية لـ API 34 على الأجهزة ذات API 34+. على الأجهزة ذات API 33 لن يتغير شيء.

// التحضير لـ targetSdk 35: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox يحد من Advertising ID من API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — المعرف غير متاح، استخدم MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // التحقق: ما التغييرات السلوكية النشطة
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

الفئة AdsManager تظهر التحضير لـ Privacy Sandbox (API 35). Advertising ID يصبح غير متاح بدءًا من API 35 مع targetSdk 35+. الدالة getActiveChanges توضح النمط الصحيح للتحقق من التغييرات السلوكية: تحتاج إلى التحقق من كل من SDK_INT للجهاز وtargetSdk للتطبيق. فقط عندما يتطابق كلا الشرطين يكون التغيير نشطًا فعليًا.

Android 15 (API 35): التغييرات السلوكية الرئيسية

Android 15 (API 35, Vanilla Ice Cream) يقدم عدة تغييرات سلوكية حرجة يجب على المطورين مراعاتها عند تحديث targetSdk إلى 35. أولاً — Privacy Sandbox for Android. هذه مبادرة Google لاستبدال Advertising ID بـ API أكثر خصوصية: Topics API (اهتمامات المستخدم)، Protected Audience (إعادة الاستهداف)، وAttribution Reporting (التحويلات). بدءًا من API 35، يتوقف Advertising ID عن كونه معرفًا ثابتًا وقد يُرجع قيمة فارغة.

التغيير الثاني — Foreground Service Types (API 34، مستمر في API 35). بدءًا من API 34، يجب على كل تطبيق ذي targetSdk 34+ تحديد نوع الخدمة الأمامية في البيان: dataSync، systemExempted، shortService، location، mediaPlayback وغيرها. بدون هذا، يُصدر النظام استثناء ForegroundServiceTypeNotAllowedException. في API 35، تمت إضافة نوع جديد health وتشديد التحقق من الأنواع الحالية. يجب مراجعة جميع الخدمات الأمامية.

التغيير الثالث — تقييد SCHEDULE_EXACT_ALARM. بدءًا من API 35، التطبيقات ذات targetSdk 35+ لا يمكنها استخدام SCHEDULE_EXACT_ALARM دون إذن صريح من المستخدم. يعرض النظام حوارًا، ويجب على المستخدم الموافقة على الجدولة الدقيقة. للمنبهات والمؤقتات، هذا يعني خطوة إضافية في تجربة المستخدم. البديل هو استخدام إنذارات غير دقيقة بهامش 10 دقائق.

// Android 15 (API 35): التحقق من SCHEDULE_EXACT_ALARM
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: مطلوب إذن المستخدم
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // أقل من API 35 — الإنذارات الدقيقة متاحة بدون إذن
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox وتقييد المنبهات هما أكثر تغييرين سلوكيين حرجين في API 35. SDK الإعلانات ستحتاج إلى الانتقال إلى Topics API وAttribution Reporting. للتطبيقات ذات المنبهات والتذكيرات — تكييف تجربة المستخدم لحوار الإذن. تجاهل هذه التغييرات سيؤدي إلى تعطل التطبيق أثناء التشغيل على Android 15 أو كسر تحقيق الدخل من الإعلانات.

الفرق بين targetSdk وcompileSdk

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

القاعدة بسيطة: compileSdk >= targetSdk >= minSdk. compileSdk عادة ما يساوي أحدث مستوى API مستقر (في 2026 — 36). targetSdk يجب أن يكون أعلى ما يمكن ضمن الإصدارات التي اختبرتها. minSdk يجب أن يكون أقل ما يمكن لأقصى تغطية. رفع compileSdk لا يتطلب اختبار التغييرات السلوكية — إنه فقط يفتح الوصول إلى API جديدة للمترجم. رفع targetSdk يتطلب دورة اختبار كاملة لجميع التغييرات السلوكية.

عمليًا: إذا كنت تريد استخدام API جديد من Android 16 (API 36) لكنك لم تختبر بعد التغييرات السلوكية لـ API 36، اضبط compileSdk = 36، targetSdk = 35. سيتم تجميع الكود مع API الجديدة، لكن التغييرات السلوكية لـ API 36 لن تُطبق. بمجرد اختبار جميع التغييرات — ارفع targetSdk إلى 36.