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

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

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

بدءًا من الإصدار Android 11 (المستوى 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) المتاحة للجميع. بدءًا من الإصدار 13 من نظام التشغيل Android (المستوى 33)، ولكنه متوفّر أيضًا على الأجهزة حتى الإصدار Android 11 (المستوى 30 لواجهة برمجة التطبيقات) طالما أنّ الجهاز يحتوي على R على الأقل إصدار 2 للإضافات:

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

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

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

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

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

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

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

التحقُّق في وقت التشغيل

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

Kotlin

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.
}

Java

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

هذا مشابه لإجراء تحقق على أساس Build.VERSION.SDK_INT:

Kotlin

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

Java

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 (مثل Android 11 و12 و12L) التي يمكنها أيضًا الوصول إلى واجهات برمجة التطبيقات إذا كان لديها امتداد R. إصدارات من 2 على الأقل.

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

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

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

Kotlin

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

Java

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

لمزيد من المعلومات عن الميزات في إضافات خدمات الإعلانات وكيفية الحصول على بدأت، راجع إضافات خدمات الإعلانات ذات الصلة.

طرق المرافق

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

دعم الأدوات

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

تضع أداة Lint علامة على الحالات التي يقل فيها الحد الأدنى من إضافات SDK لم يتم استيفاء الإصدار المطلوب لطلب واجهة برمجة التطبيقات.

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

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

اسم إضافة حزمة تطوير البرامج (SDK)	ثابت	الأجهزة المؤهَّلة
امتدادات R	VERSION_CODES.R	Android 11 (المستوى 30) والإصدارات الأحدث
إضافات S	VERSION_CODES.S	Android 12 (المستوى 31) والإصدارات الأحدث
إضافات T	VERSION_CODES.TIRAMISU	Android 13 (المستوى 33) والإصدارات الأحدث
إضافات الخدمات الإعلانية	SdkExtensions.AD_SERVICES	Android 13 (المستوى 33) والإصدارات الأحدث

التحقّق باستخدام 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 في هذه الحالة).