إضافات حزمة تطوير البرامج (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 لواجهة برمجة التطبيقات) طالما أنّ الجهاز يحتوي على الإصدار 2 من إضافات R على الأقل:

تعرض واجهات برمجة التطبيقات التي تكون جزءًا من إضافات SDK إصدار الإضافة في المستندات المرجعية لواجهة برمجة التطبيقات.

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

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

  1. ابحث عن الحد الأدنى لإصدار الإضافات الذي تحتاجه من خلال مراجعة وثائق الميزات ومرجع واجهة برمجة التطبيقات لواجهات برمجة التطبيقات التي تريد استخدامها.
  2. بعد تحديد إصدار الإضافة المطلوب لمجموعة الميزات، افتح SDK Manager في Android Studio.
  3. اختَر إدخال Android SDK Platform مع إصدار الإضافة المقابل (أو إصدار أحدث، لأنّ واجهات برمجة التطبيقات هي إضافات). على سبيل المثال: Android SDK Platform 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 لواجهة برمجة التطبيقات) متاحًا:

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 API في بعض الأحيان إلى أنّ واجهة برمجة التطبيقات هي جزء من إصدار "إضافات الخدمات الإعلانية". على عكس إضافات حزم تطوير البرامج (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 library للتحقق من مدى توفّر Photo Picker، فهي تزيل عمليات التحقق من الإصدار المشروط.

دعم الأدوات

في Android Studio Flamingo | 2022.2.1 أو الإصدارات الأحدث، يمكن لأداة lint_ الطلب البحث عن المشاكل المتعلّقة بإصدارات إضافات SDK كجزء من عملية التحقق من واجهة برمجة التطبيقات الجديدة. بالإضافة إلى ذلك، يمكن لاستوديو 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 في هذه الحالة).