إضافات حِزم تطوير البرامج (SDK)

تستفيد إضافات حزمة SDK من مكوّنات النظام النمطية لإضافة واجهات برمجة تطبيقات إلى حزمة SDK العامة لمستويات معيّنة من واجهات برمجة التطبيقات التي تم إصدارها سابقًا. يتم توفير واجهات برمجة التطبيقات هذه للأجهزة عندما يتلقّى المستخدمون النهائيون تحديثات الوحدات من خلال تحديثات نظام Google Play. يمكن لمطوّري التطبيقات الاستفادة من واجهات برمجة التطبيقات هذه في تطبيقاتهم لتوفير وظائف إضافية لم تكن متاحة في حزمة تطوير البرامج (SDK) لهذه الإصدارات السابقة من Android.

تحديد إصدارات واجهة برمجة التطبيقات

بدءًا من الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات)، تتضمّن أجهزة Android مجموعة من إضافات حزمة تطوير البرامج (SDK). عند إضافة واجهات برمجة تطبيقات جديدة، يتم تضمينها في مستوى واجهة برمجة تطبيقات، ولكن يمكن أيضًا تضمينها في إضافة حزمة تطوير برامج (SDK) لإصدار معيّن. على سبيل المثال، تمت إضافة واجهة برمجة التطبيقات ACTION_PICK_IMAGES الخاصة بأداة اختيار الصور إلى حزمة تطوير البرامج (SDK) العامة في نظام التشغيل Android 13 (مستوى واجهة برمجة التطبيقات 33)، ولكنها متاحة أيضًا من خلال إضافات حزمة تطوير البرامج (SDK) بدءًا من الإصدار 2 من إضافات R. تتوافق أسماء إضافات حزمة SDK مع ثابت عدد صحيح، إما ثابت من Build.VERSION_CODES أو ثابت محدّد في الفئة SdkExtensions (مثل SdkExtensions.AD_SERVICES).

تحديد إضافات حزمة تطوير البرامج (SDK) التي سيتم استخدامها

قبل استخدام واجهات برمجة التطبيقات الخاصة بإضافات حِزم SDK، عليك أولاً تحديد حِزم SDK التي تتضمّن واجهات برمجة التطبيقات المتوافقة مع حالات استخدام تطبيقك.

تحدّد صفحات مرجع واجهة برمجة التطبيقات الخاصة بإضافات حزمة تطوير البرامج (SDK) الإصدار الأقدم من إضافة حزمة تطوير البرامج (SDK) الذي يمكن أن يستخدمه تطبيقك للوصول إلى واجهة برمجة التطبيقات. وإذا كانت المستندات تحدّد أيضًا إصدارًا من نظام Android الأساسي (يُشار إليه بمستوى واجهة برمجة التطبيقات)، ستكون واجهة برمجة التطبيقات هذه متاحة أيضًا لجميع الأجهزة التي تعمل بهذا الإصدار من نظام Android الأساسي أو إصدار أحدث.

على سبيل المثال، تتوفّر ACTION_PICK_IMAGES بشكل عام في حزمة تطوير البرامج (SDK) العامة بدءًا من Android 13 (مستوى واجهة برمجة التطبيقات 33)، ولكنها تتوفّر أيضًا على الأجهزة التي تعمل بالإصدار 11 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 30) أو الإصدارات الأحدث، طالما أنّ الجهاز يتضمّن الإصدار 2 على الأقل من حزمة R Extensions:

لاستخدام واجهة برمجة التطبيقات هذه، يجب إجراء عملية تجميع باستخدام حزمة تطوير برامج (SDK) بمستوى واجهة برمجة تطبيقات 33 على الأقل أو مستوى إضافة 2 على الأقل.

لاستخدام حزمة تطوير برامج (SDK) خاصة بإحدى الإضافات، اتّبِع الخطوات التالية:

1. ابحث عن الحد الأدنى من إصدار الإضافات الذي تحتاجه من خلال الاطّلاع على مستندات الميزة ومرجع واجهة برمجة التطبيقات الخاصة بواجهات برمجة التطبيقات التي تريد استخدامها.
2. بعد تحديد إصدار الإضافة المطلوب لمجموعة الخصائص، افتح SDK Manager في استوديو Android.
3. اختَر إدخال "نظام Android الأساسي لحزمة تطوير البرامج" (Android SDK Platform) مع إصدار الإضافة المطابق (أو إصدار أعلى، لأنّ واجهات برمجة التطبيقات تراكمية). على سبيل المثال: الإصدار 33 من "منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android"، المستوى 4 من حزمة تطوير البرامج (SDK)

4. يجب تعريف هذه القيم في ملف build.gradle.kts أو build.gradle الخاص بتطبيقك:

   أنيق

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   Kotlin

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }

التحقّق من توفّر "إضافات حزمة تطوير البرامج"

يمكن لتطبيقك التحقّق من إصدارات حزمة SDK المتوفّرة في وقت التشغيل، ويمكنك أثناء التطوير البحث عن إصدارات الحزمة باستخدام أوامر "جسر تصحيح أخطاء Android" (adb)، كما هو موضّح في الأقسام التالية.

التحقّق أثناء التشغيل

يمكن لتطبيقك التحقّق في وقت التشغيل مما إذا كانت "إضافات حزمة تطوير البرامج" متاحة لإصدار نظام أساسي معيّن باستخدام الطريقة getExtensionVersion(). على سبيل المثال، يتحقّق الرمز التالي مما إذا كان الإصدار 2 أو إصدار أحدث من "إضافة حزمة تطوير البرامج" لنظام التشغيل Android 11 (مستوى واجهة برمجة التطبيقات 30) متاحًا:

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

يشبه ذلك إجراء عملية تحقّق استنادًا إلى Build.VERSION.SDK_INT:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

لا يزال التحقّق SDK_INT آمنًا وصالحًا، ولكن isPhotoPickerAvailable سيعرض القيمة "خطأ" على بعض الأجهزة على الرغم من توفّر واجهة برمجة التطبيقات الخاصة بالإضافات. ونتيجةً لذلك، لا يُعدّ التحقّق SDK_INT مثاليًا، ويُعدّ التحقّق من إصدار الإضافة طريقة أفضل للتحقّق من توفّر واجهة برمجة التطبيقات. تتضمّن جميع الأجهزة التي يكون فيها SDK_INT أكبر من أو يساوي 33 (الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث) واجهات برمجة التطبيقات الخاصة بأداة اختيار الصور في حزمة تطوير البرامج (SDK) العامة، ولكن هناك أجهزة يكون فيها SDK_INT أقل من 33 (مثل الإصدارات 11 و12 و12L من نظام التشغيل Android) يمكنها أيضًا الوصول إلى واجهات برمجة التطبيقات إذا كانت تتضمّن إصدارات الإضافة R التي لا تقل عن 2.

في هذه الحالة، يمكن أن يساعد استخدام عملية التحقّق من إصدار الإضافة تطبيقك في توفير وظائف إضافية للمزيد من المستخدمين. اطّلِع على أسماء ثوابت إضافات حزمة SDK للحصول على قائمة بجميع الثوابت التي يمكنك استخدامها للتحقّق من توفّر إضافات حزمة SDK معيّنة على جهاز.

إضافات خدمات الإعلانات

على غرار المجموعة العامة من إضافات حزمة تطوير البرامج (SDK)، يشير مرجع واجهة برمجة التطبيقات AdServices في بعض الأحيان إلى أنّ إحدى واجهات برمجة التطبيقات هي جزء من إصدار "إضافات خدمات الإعلانات". على عكس إضافات حزمة تطوير البرامج (SDK) العامة، تستخدم إضافات "خدمات الإعلانات" الثابت SdkExtensions.AD_SERVICES لتحديد الإصدار المتوفّر على الجهاز:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

لمزيد من المعلومات حول الميزات في "إضافات خدمات الإعلانات" وكيفية البدء، يُرجى الاطّلاع على مستندات "إضافات خدمات الإعلانات".

طُرق الأدوات المساعدة

في بعض الحالات، تتضمّن إضافات حزمة تطوير البرامج (SDK) طرقًا مساعدة في Jetpack للتحقّق من توفّر واجهات برمجة التطبيقات الخاصة بإضافات حزمة تطوير البرامج (SDK). على سبيل المثال، يمكنك استخدام دالة مكتبة Jetpack للتحقّق من توفّر PhotoPicker، التي تجرّد عمليات التحقّق الشرطية من الإصدار.

الأدوات المتوافقة

في الإصدار Android Studio Flamingo | 2022.2.1 أو الإصدارات الأحدث، يمكن لأداة lint البحث عن مشاكل في إصدارات حزمة SDK كجزء من عملية التحقّق من NewAPI. بالإضافة إلى ذلك، يمكن لـ "استوديو Android" إنشاء عمليات التحقّق الصحيحة من الإصدارات تلقائيًا لواجهات برمجة التطبيقات التي يتم إطلاقها باستخدام حِزم SDK.

أسماء ثوابت إضافات حزمة تطوير البرامج (SDK)

يوضّح الجدول التالي كيفية ربط المجموعات المختلفة من إضافات حزمة تطوير البرامج (SDK) المدرَجة في مستندات مرجع واجهة برمجة التطبيقات بالثوابت التي يمكن أن يستخدمها تطبيقك للتحقّق من توفّر واجهة برمجة التطبيقات في وقت التشغيل. تتطابق المجموعة العامة من إضافات حزمة تطوير البرامج (SDK) لكل حزمة SDK عامة مع قيم Build.VERSION_CODES.

التحقّق باستخدام adb

للتحقّق من حِزم SDK Extensions المتوفّرة على جهاز باستخدام adb، شغِّل الأمر التالي:

adb shell getprop | grep build.version.extensions

بعد تنفيذ الأمر، ستظهر لك نتيجة مشابهة لما يلي:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

يعرض كل سطر إحدى إضافات حزمة تطوير البرامج (SDK) المتوفّرة على الجهاز، بالإضافة إلى إصدار الإضافة المعنيّة (الإصدار 3 في هذه الحالة).