<uses-sdk>

يستخدم Google Play سمات <uses-sdk> الموضَّحة في بيان تطبيقك لفلترة تطبيقك من الأجهزة التي لا تستوفي متطلبات إصدار النظام الأساسي. قبل ضبط هذه السمات، تأكَّد من فهمك لفلاتر Google Play.

البنية:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
مضمّنة في:
<manifest>
description:

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

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

لا يمكن تحديد أنّ التطبيق يستهدف إصدارًا ثانويًا من حزمة SDK أو يتطلّبه.

يمكنك أيضًا قراءة المستند حول تحديد إصدارات تطبيقاتك.

السمات:
android:minSdkVersion
عدد صحيح يحدّد الحد الأدنى لمستوى واجهة برمجة التطبيقات المطلوب لتشغيل التطبيق. يمنع نظام Android المستخدم من تثبيت التطبيق إذا كان مستوى واجهة برمجة التطبيقات للنظام أقل من القيمة المحدّدة في هذه السمة. يجب دائمًا تحديد هذه السمة.

تنبيه: إذا لم تذكر هذه السمة، يفترض النظام أنّ القيمة التلقائية هي "1"، ما يشير إلى أنّ تطبيقك متوافق مع جميع إصدارات Android. وإذا لم يكن متوافقًا ولم تُعرِّف السمة minSdkVersion المناسبة، سيتعطّل التطبيق أثناء التشغيل عند محاولة الوصول إلى واجهات برمجة التطبيقات غير المتاحة، وذلك في حال تثبيته على نظام يتضمّن مستوى واجهة برمجة تطبيقات غير متوافق. لهذا السبب، احرص على تحديد مستوى واجهة برمجة التطبيقات المناسب في السمة minSdkVersion.

android:targetSdkVersion
عدد صحيح يحدّد مستوى واجهة برمجة التطبيقات الذي يستهدفه التطبيق. وفي حال عدم ضبطها، تساوي القيمة التلقائية القيمة المحدّدة للسمة minSdkVersion.

تُعلم هذه السمة النظام بأنّك اختبرت التطبيق على الإصدار المستهدَف، ولا يفعّل النظام أي سلوكيات توافق للحفاظ على التوافق مع الإصدارات المستقبلية من تطبيقك مع الإصدار المستهدَف. سيظل بإمكان التطبيق العمل على الإصدارات الأقدم (حتى الإصدار minSdkVersion).

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

على سبيل المثال، يؤدي ضبط هذه القيمة على "11" أو أعلى إلى السماح للنظام بتطبيق المظهر التلقائي Holo على تطبيقك عند تشغيله على Android 3.0 أو أعلى، كما يؤدي إلى إيقاف وضع التوافق مع حجم الشاشة عند تشغيله على الشاشات الأكبر حجمًا، لأنّ التوافق مع مستوى واجهة برمجة التطبيقات 11 يتوافق ضمنيًا مع الشاشات الأكبر حجمًا.

هناك العديد من سلوكيات التوافق التي يمكن للنظام تفعيلها استنادًا إلى القيمة التي تحدّدها لهذه السمة. يتم وصف العديد من هذه السلوكيات من خلال إصدارات المنصة المقابلة في مرجع Build.VERSION_CODES.

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

تاريخ الطرح: مستوى واجهة برمجة التطبيقات 4

android:maxSdkVersion
عدد صحيح يحدّد الحد الأقصى لمستوى واجهة برمجة التطبيقات الذي تم تصميم التطبيق ليعمل عليه.

In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this attribute when installing an application and when re-validating the application after a system update. وفي كلتا الحالتين، إذا كانت سمة maxSdkVersion للتطبيق أقل من مستوى واجهة برمجة التطبيقات الذي يستخدمه النظام نفسه، لن يسمح النظام بتثبيت التطبيق. في حال إعادة التحقّق بعد تحديث النظام، يؤدي ذلك إلى إزالة تطبيقك من الجهاز.

لتوضيح كيف يمكن أن تؤثر هذه السمة في تطبيقك بعد تحديثات النظام، إليك المثال التالي:

تم نشر تطبيق على Google Play يعلن عن maxSdkVersion="5" في ملف البيان الخاص به. يُنزِّل مستخدم التطبيق ويثبِّته على جهاز يعمل بالإصدار 1.6 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 4). وبعد بضعة أسابيع، يتلقّى المستخدم تحديثًا للنظام عبر شبكة غير سلكية إلى الإصدار 2.0 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 5). بعد تثبيت التحديث، يتحقّق النظام من maxSdkVersion للتطبيق ويعيد التحقّق منه بنجاح.

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

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

تاريخ الطرح: مستوى واجهة برمجة التطبيقات 4

لا تتحقّق بعض إصدارات Android (بعد الإصدار 2.0.1) من السمة maxSdkVersion أو تفرضها أثناء التثبيت أو إعادة التحقّق. ومع ذلك، يواصل Google Play استخدام السمة كفلتر عند عرض التطبيقات المتاحة للمستخدمين لتنزيلها.
تم إدخال القدرة لأول مرة في:
مستوى واجهة برمجة التطبيقات 1

ما هو مستوى واجهة برمجة التطبيقات؟

مستوى واجهة برمجة التطبيقات هو قيمة عددية صحيحة تحدّد بشكل فريد مراجعة واجهة برمجة التطبيقات لإطار العمل التي يوفّرها إصدار من نظام Android الأساسي.

يوفّر نظام Android الأساسي واجهة برمجة تطبيقات لإطار العمل يمكن للتطبيقات استخدامها للتفاعل مع نظام Android الأساسي. تتألف واجهة برمجة التطبيقات الخاصة بإطار العمل من:

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

يمكن أن يتضمّن كل إصدار متتالٍ من نظام Android الأساسي تحديثات لواجهة برمجة التطبيقات لإطار عمل تطبيقات Android التي يوفّرها.

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

في عدد قليل جدًا من الحالات، يتم تعديل أجزاء من واجهة برمجة التطبيقات أو إزالتها، على الرغم من أنّ هذه التغييرات عادةً ما تكون مطلوبة فقط لتعزيز فعالية واجهة برمجة التطبيقات وأمان التطبيق أو النظام. ويتم نقل جميع أجزاء واجهة برمجة التطبيقات الأخرى من النُسخ السابقة بدون تعديل.

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

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

إصدار النظام الأساسيمستوى واجهة برمجة التطبيقاتVERSION_CODEملاحظات
Android 17 37 CINNAMON_BUN أبرز ميزات المنصة
Android 16 36 BAKLAVA أبرز ميزات المنصة
Android 15 35 VANILLA_ICE_CREAM أبرز ميزات المنصة
Android 14 34 UPSIDE_DOWN_CAKE أبرز ميزات المنصة
Android 13 33 TIRAMISU أبرز ميزات المنصة
Android 12 32 S_V2 أبرز ميزات المنصة
31 S أبرز ميزات المنصة
Android 11 30 R أبرز ميزات المنصة
Android 10 29 Q أبرز ميزات المنصة
Android 9 28 P أبرز ميزات المنصة
Android 8.1 27 O_MR1 أبرز ميزات المنصة
Android 8.0 26 O أبرز ميزات المنصة
Android 7.1.1
Android 7.1		 25 N_MR1 أبرز ميزات المنصة
Android 7.0 24 N أبرز ميزات المنصة
Android 6.0 23 M أبرز ميزات المنصة
Android 5.1 22 LOLLIPOP_MR1 أبرز ميزات المنصة
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat للأجهزة القابلة للارتداء فقط
Android 4.4 19 KITKAT أبرز ميزات المنصة
Android 4.3 18 JELLY_BEAN_MR2 أبرز ميزات المنصة
الإصداران 4.2 و4.2.2 من نظام التشغيل Android 17 JELLY_BEAN_MR1 أبرز ميزات المنصة
الإصداران 4.1 و4.1.1 من نظام التشغيل Android 16 JELLY_BEAN أبرز ميزات المنصة
الإصداران 4.0.3 و4.0.4 من Android 15 ICE_CREAM_SANDWICH_MR1 أبرز ميزات المنصة
الإصدارات 4.0 و4.0.1 و4.0.2 من نظام التشغيل Android 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
الإصدار 3.1.x من Android 12 HONEYCOMB_MR1 أبرز ميزات المنصة
الإصدار 3.0.x من Android 11 HONEYCOMB أبرز ميزات المنصة
Android 2.3.4
Android 2.3.3		 10 GINGERBREAD_MR1 أبرز ميزات المنصة
Android 2.3.2
Android 2.3.1
Android 2.3		 9 GINGERBREAD
Android 2.2.x 8 FROYO أبرز ميزات المنصة
الإصدار 2.1.x من Android 7 ECLAIR_MR1 أبرز ميزات المنصة
الإصدار 2.0.1 من Android 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT أبرز ميزات المنصة
Android 1.5 3 CUPCAKE أبرز ميزات المنصة
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

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

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

  • حالة المعاينة قبل الإصدار: تكون الإضافة أو الإيقاف النهائي لواجهة برمجة التطبيقات جزءًا من إصدار حزمة تطوير البرامج (SDK) للمعاينة النشطة في الإصدار التجريبي أو الإصدار Canary قبل الانتهاء من مستوى واجهة برمجة التطبيقات.
  • عدم ضمان الاستقرار: على عكس واجهات برمجة التطبيقات التي تم إصدارها (والتي لها مستوى واجهة برمجة تطبيقات دائم ومتوافقة مع الأنظمة القديمة في الإصدارات المستقبلية)، قد تتغيّر توقيعات واجهات برمجة التطبيقات قيد التطوير أو تتم إعادة تسميتها أو إزالتها بالكامل بين إصدارات حزمة تطوير البرامج (SDK) الحصرية.

التحقّق من واجهات برمجة التطبيقات قيد التطوير في وقت التشغيل (PREVIEW_SDK_INT)

بما أنّ واجهات برمجة التطبيقات قيد التطوير يمكن أن تتغيّر أو تختفي بين الإصدارات المبكرة الحصرية، لا تستخدِم أبدًا عملية التحقّق من القيمة الأكبر من أو تساوي (>=) لحماية طلبات البيانات من واجهات برمجة التطبيقات التي لم يتم إصدارها. قد يتم تعديل أو حذف واجهة برمجة تطبيقات موجودة في النسخة الحصرية 1 في النسخة الحصرية 2.

بدلاً من ذلك، يجب أن تتحقّق التطبيقات التي تجرّب الميزات المسبقة من قيمة Build.VERSION.PREVIEW_SDK_INT للتأكّد من المساواة الصارمة (==) مع نسخة المراجعة المسبقة الدقيقة التي تم تجميع التطبيق وفقًا لها:

  • في الإصدارات النهائية والإصدارات العلنية، تكون قيمة Build.VERSION.PREVIEW_SDK_INT دائمًا 0.
  • في إصدارات المعاينة، يكون PREVIEW_SDK_INT فريدًا لكل إصدار.

استخدامات مستوى واجهة برمجة التطبيقات في Android

يؤدي معرّف مستوى واجهة برمجة التطبيقات دورًا رئيسيًا في المساعدة على ضمان أفضل تجربة ممكنة للمستخدمين ومطوّري التطبيقات:

  • تتيح هذه السمة لنظام Android الأساسي وصف الحد الأقصى لمراجعة واجهة برمجة التطبيقات لإطار العمل التي يتوافق معها.
  • تتيح للتطبيقات وصف مراجعة واجهة برمجة التطبيقات لإطار العمل التي تتطلبها.
  • ويتيح للنظام التفاوض بشأن تثبيت التطبيقات على جهاز المستخدم حتى لا يتم تثبيت التطبيقات غير المتوافقة مع الإصدار.

يخزّن كل إصدار من نظام Android الأساسي معرّف مستوى واجهة برمجة التطبيقات داخليًا في نظام Android نفسه.

يمكن للتطبيقات استخدام عنصر بيان توفّره واجهة برمجة التطبيقات لإطار العمل، وهو <uses-sdk>، لوصف الحدّ الأدنى والحدّ الأقصى لمستويات واجهة برمجة التطبيقات التي يمكن تشغيلها ضمنها، بالإضافة إلى المستوى المفضّل لواجهة برمجة التطبيقات الذي تم تصميمها لدعمه. يوفّر العنصر ثلاث سمات رئيسية:

  • ‫android:minSdkVersion: الحد الأدنى لمستوى واجهة برمجة التطبيقات الذي يمكن تشغيل التطبيق عليه القيمة التلقائية هي "1".
  • ‫android:targetSdkVersion: مستوى واجهة برمجة التطبيقات الذي تم تصميم التطبيق ليعمل عليه في بعض الحالات، يتيح ذلك للتطبيق استخدام عناصر البيان أو السلوكيات المحدّدة في مستوى واجهة برمجة التطبيقات المستهدف، بدلاً من أن يقتصر على استخدام العناصر المحدّدة للحد الأدنى لمستوى واجهة برمجة التطبيقات فقط.
  • ‫android:maxSdkVersion: الحد الأقصى لمستوى واجهة برمجة التطبيقات الذي يمكن تشغيل التطبيق عليه ملاحظة مهمة: اقرأ المعلومات حول هذه السمة في هذه الصفحة قبل استخدامها.

على سبيل المثال، لتحديد الحد الأدنى لمستوى واجهة برمجة التطبيقات للنظام الذي يتطلبه التطبيق لكي يعمل، يتضمّن التطبيق في بيانه عنصر <uses-sdk> مع سمة android:minSdkVersion. قيمة android:minSdkVersion هي العدد الصحيح المقابل لمستوى واجهة برمجة التطبيقات لأقدم إصدار من نظام Android الأساسي الذي يمكن تشغيل التطبيق عليه.

عندما يحاول المستخدم تثبيت تطبيق، أو عند إعادة التحقّق من صحة تطبيق بعد تحديث النظام، يتحقّق نظام Android أولاً من سمات <uses-sdk> في بيان التطبيق ويقارن القيم بمستوى واجهة برمجة التطبيقات الداخلي الخاص به. يسمح النظام ببدء عملية التثبيت فقط في حال استيفاء الشروط التالية:

  • إذا تم تحديد سمة android:minSdkVersion، تكون قيمتها أقل من أو تساوي العدد الصحيح لمستوى واجهة برمجة التطبيقات في النظام. وفي حال عدم تحديده، يفترض النظام أنّ التطبيق يتطلّب المستوى 1 من واجهة برمجة التطبيقات.
  • في حال تحديد سمة android:maxSdkVersion، تكون قيمتها مساوية لعدد صحيح لمستوى واجهة برمجة التطبيقات في النظام أو أكبر منه. إذا لم يتم تحديد هذا المستوى، يفترض النظام أنّ التطبيق ليس له حدّ أقصى لمستوى واجهة برمجة التطبيقات. يمكنك قراءة وصف هذه السمة لمزيد من المعلومات حول كيفية معالجة النظام لها.

عند الإعلان عن عنصر <uses-sdk> في بيان التطبيق، قد يبدو كما يلي: 

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

السبب الرئيسي وراء تعريف التطبيق لمستوى واجهة برمجة التطبيقات في android:minSdkVersion هو إعلام نظام Android بأنّه يستخدم واجهات برمجة التطبيقات التي تم تقديمها في مستوى واجهة برمجة التطبيقات المحدّد.

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

اعتبارات التطوير

تقدّم الأقسام التالية معلومات متعلقة بمستوى واجهة برمجة التطبيقات التي يجب مراعاتها عند تطوير تطبيقك.

التوافق مع الإصدارات الأحدث من التطبيقات

تتوافق تطبيقات Android بشكل عام مع الإصدارات الجديدة من نظام Android الأساسي.

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

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

يمكن أن تؤثر التغييرات أدناه في واجهة برمجة التطبيقات، مثل تلك الموجودة في النظام الأساسي نفسه، في تطبيقك عند تشغيله في البيئة الجديدة. من المهم بالنسبة إليك، بصفتك مطوّر التطبيق، أن تفهم كيف يبدو التطبيق ويتصرف في كل بيئة نظام.

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

توافق التطبيق مع الأنظمة القديمة

لا تتوافق تطبيقات Android بالضرورة مع الإصدارات القديمة من نظام Android الأساسي التي تسبق الإصدار الذي تم تجميعها عليه.

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

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

اختيار إصدار نظام أساسي ومستوى واجهة برمجة تطبيقات

عند تطوير تطبيقك، يمكنك اختيار إصدار النظام الأساسي الذي يتم تجميع التطبيق من خلاله. بشكل عام، عليك تجميع تطبيقك وفقًا لأدنى إصدار ممكن من المنصة يمكن لتطبيقك دعمه.

يمكنك تحديد أدنى إصدار ممكن للنظام الأساسي من خلال تجميع التطبيق مقابل أهداف إصدار أقل على التوالي. بعد تحديد الإصدار الأدنى، أنشئ جهاز Android افتراضيًا باستخدام إصدار النظام الأساسي ومستوى واجهة برمجة التطبيقات المناسبَين، واختبِر تطبيقك بالكامل. تأكَّد من الإفصاح عن سمة android:minSdkVersion في بيان التطبيق وضبط قيمتها على مستوى واجهة برمجة التطبيقات لإصدار النظام الأساسي.

تعريف الحد الأدنى لمستوى واجهة برمجة التطبيقات

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

إذا كان تطبيقك يستخدم واجهات برمجة التطبيقات التي تم تقديمها في أحدث إصدار من النظام الأساسي ولكنّه لا يعلن عن سمة android:minSdkVersion، فسيتم تشغيله بشكل صحيح على الأجهزة التي تعمل بأحدث إصدار من النظام الأساسي، ولكن ليس على الأجهزة التي تعمل بإصدارات سابقة من النظام الأساسي. وفي الحالة الأخيرة، يتعطّل التطبيق في وقت التشغيل عندما يحاول استخدام واجهات برمجة التطبيقات غير المتوفّرة في الإصدارات السابقة.

الاختبار على مستويات أعلى من واجهة برمجة التطبيقات

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

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

للوصول إلى أداة التحديث، استخدِم أداة سطر الأوامر android الموجودة في الدليل <sdk>/tools. يمكنك تشغيل أداة تحديث حزمة SDK من خلال تنفيذ android sdk. يمكنك أيضًا النقر مرّتين على الملف android.bat (Windows) أو android (OS X/Linux).

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

فلترة المستندات المرجعية حسب مستوى واجهة برمجة التطبيقات

توفّر صفحات المستندات المرجعية لنظام Android الأساسي عنصر تحكّم في "مستوى واجهة برمجة التطبيقات" في أعلى يمين كل صفحة. يمكنك استخدام عنصر التحكّم لعرض المستندات فقط لأجزاء واجهة برمجة التطبيقات التي يمكن لتطبيقك الوصول إليها فعليًا، استنادًا إلى مستوى واجهة برمجة التطبيقات الذي يحدّده في سمة android:minSdkVersion لملف البيان الخاص به.

لاستخدام الفلترة، اختَر مستوى واجهة برمجة التطبيقات الذي يحدّده تطبيقك من القائمة. بعد ذلك، تظهر واجهات برمجة التطبيقات التي تم تقديمها في مستوى واجهة برمجة تطبيقات لاحق باللون الرمادي ويتم حجب محتواها، لأنّها غير متاحة لتطبيقك.

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

للرجوع إلى عرض المستندات الكاملة، اختَر REL في أعلى قائمة مستوى واجهة برمجة التطبيقات. يتم تلقائيًا إيقاف فلترة مستوى واجهة برمجة التطبيقات، لكي تتمكّن من عرض واجهة برمجة التطبيقات الكاملة لإطار العمل، بغض النظر عن مستوى واجهة برمجة التطبيقات.

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