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

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

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

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

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

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

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

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

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

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

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

4. حدِّد هذه القيم في ملف build.gradle.kts أو build.gradle لتطبيقك:

   رائع

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

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

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

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

يمكن لتطبيقك التحقّق أثناء التشغيل مما إذا كانت "إضافات حِزم تطوير البرامج (SDK)" متاحة لإصدار معيّن من المنصة باستخدام الوسيطة getExtensionVersion(). على سبيل المثال، سيتحقّق الرمز البرمجي التالي ممّا إذا كان الإصدار 2 أو إصدار أحدث من حزمة SDK لنظام التشغيل 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 ‎greater than or equal to 33 (Android 13 أو إصدار أحدث) على واجهات برمجة التطبيقات الخاصة بأداة اختيار الصور في حزمة تطوير البرامج (SDK) العلنية، ولكن هناك أجهزة تعمل بالإصدار SDK_INT أقل من 33 (مثل Android 11 و12 و12L) يمكنها أيضًا الوصول إلى واجهات برمجة التطبيقات إذا كانت تحتوي على إصدارات 2 على الأقل من إضافة R.

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

إضافات خدمات Google الإعلانية

على غرار المجموعة العامة من "إضافات حِزم تطوير البرامج (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 للتحقّق من توفّر واجهات برمجة التطبيقات الخاصة بها. على سبيل المثال، يمكنك استخدام دالة مكتبة Jetpack للتحقق من availability لـ PhotoPicker، التي تزيل عمليات التحقّق من الإصدارات الشَرطية.

دعم الأدوات

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

أسماء ملحق حزمة SDK والثوابت

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

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

للتحقّق من الإضافات المتاحة لحزمة تطوير البرامج (SDK) على جهاز باستخدام 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 في هذه الحالة).