<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 على تطبيقك عند تشغيله على الإصدار 3.0 من نظام التشغيل Android أو الإصدارات الأحدث، كما يؤدي إلى إيقاف وضع توافق الشاشة عند تشغيله على شاشات أكبر، لأنّ توفير الدعم للمستوى 11 من واجهة برمجة التطبيقات يتيح ضِمنًا إمكانية تشغيله على شاشات أكبر.

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

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

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

android:maxSdkVersion

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

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

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

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

تعمل التطبيقات بشكل طبيعي. ومع ذلك، بعد فترة من الوقت، يتلقّى الجهاز تحديثًا آخر للنظام، هذه المرة إلى الإصدار 2.0.1 من Android (المستوى 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 الأساسي. للحصول على معلومات حول الأعداد النسبية للأجهزة التي تعمل بكل إصدار، راجِع لوحة بيانات التوزيع.

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

في مستندات مرجع Android API، يتم وضع علامة "واجهة برمجة تطبيقات قيد التطوير" على بعض واجهات برمجة التطبيقات بدلاً من مستوى واجهة برمجة تطبيقات عدد صحيح. تتضمّن واجهات برمجة التطبيقات قيد التطوير الخصائص التالية:

• حالة المعاينة المسبقة للإصدار: تشكّل واجهات برمجة التطبيقات هذه حاليًا جزءًا من إصدار تجريبي أو Canary نشط من حزمة تطوير البرامج (SDK) الخاصة بالمعاينة، ولم يتم بعد الوصول إلى مرحلة استقرار النظام الأساسي.
• لا نضمن الثبات: على عكس واجهات برمجة التطبيقات التي تم إصدارها (والتي لها مستوى دائم لواجهة برمجة التطبيقات وتتوافق مع الإصدارات السابقة في جميع الإصدارات المستقبلية)، قد تتغير توقيعات واجهات برمجة التطبيقات قيد التطوير أو تتم إعادة تسميتها أو إزالتها بالكامل بين إصدارات حزمة تطوير البرامج (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). قد يثبّت المستخدم تطبيقك ويستخدمه بنجاح، ثم يتلقّى لاحقًا تحديثًا عبر الأثير (OTA) إلى إصدار جديد من نظام Android الأساسي. بعد تثبيت التحديث، سيتم تشغيل تطبيقك في إصدار جديد من بيئة وقت التشغيل، ولكن سيظل يتضمّن إمكانات واجهة برمجة التطبيقات والنظام التي يعتمد عليها تطبيقك.

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

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

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

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

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

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

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

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

يمكنك تحديد أدنى إصدار ممكن من النظام الأساسي عن طريق تجميع التطبيق مع استهداف إصدارات أدنى على التوالي. بعد تحديد الإصدار الأدنى، أنشئ جهاز AVD باستخدام إصدار النظام الأساسي ومستوى واجهة برمجة التطبيقات المناسبَين، واختبِر تطبيقك بالكامل. احرص على تعريف السمة 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 في أعلى قائمة مستوى واجهة برمجة التطبيقات. يكون فلترة مستوى واجهة برمجة التطبيقات غير مفعَّلة تلقائيًا، ما يتيح لك عرض واجهة برمجة التطبيقات الكاملة للإطار، بغض النظر عن مستوى واجهة برمجة التطبيقات.

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