أدوات إطار عمل التوافق

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

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

كيفية تحديد التغييرات المفعَّلة

عند تفعيل تغيير في السلوك، يمكن أن يؤثر ذلك في كيفية وصول تطبيقك إلى واجهات برمجة التطبيقات الخاصة بالمنصة والمتأثرة بهذا التغيير. يمكنك التحقّق من التغييرات المفعَّلة في السلوك باستخدام خيارات المطوّرين أو logcat أو أوامر ADB.

تحديد التغييرات المفعَّلة باستخدام خيارات المطوّرين

الشكل 1: "تغييرات توافق التطبيقات" في خيارات المطوّرين.

يمكنك الاطّلاع على التغييرات المفعَّلة وتفعيلها أو إيقافها في خيارات المطوّرين على الجهاز. للوصول إلى هذه الخيارات، اتّبِع الخطوات التالية:

1. إذا لم تكن خيارات المطوّرين مفعَّلة، عليك تفعيلها.
2. افتح تطبيق "الإعدادات" على جهازك وانتقِل إلى النظام > الإعدادات المتقدّمة > خيارات المطوّرين > تغييرات توافق التطبيقات.

3. اختَر تطبيقك من القائمة.

يندرج كل تغيير في السلوك عادةً ضمن إحدى الفئتَين التاليتَين:

• التغييرات التي تؤثر في جميع التطبيقات التي تعمل على هذا الإصدار من Android، بغض النظر عن targetSdkVersion للتطبيق.

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

• التغييرات التي تؤثّر فقط في التطبيقات التي تستهدف إصدارات معيّنة من Android بما أنّ هذه التغييرات لا تؤثر إلا في التطبيقات التي تستهدف إصدارًا معيّنًا من Android، يُشار إليها أيضًا باسم التغييرات المقيَّدة حسب targetSDKVersion.

  يتم تفعيل هذه التغييرات تلقائيًا في إطار عمل التوافق إذا كان تطبيقك يستهدف إصدارًا أحدث من إصدار واجهة برمجة التطبيقات المُدرَج. على سبيل المثال، سيتم إدراج تغيير في السلوك يتم التحكّم فيه من خلال targetSDKVersion في Android 13 (المستوى 33 لواجهة برمجة التطبيقات) في واجهة المستخدم ضمن قسم بعنوان مفعَّل لـ targetSdkVersion >=33. في بعض إصدارات Android الأقدم، يُطلق على هذا القسم اسم "مفعَّل بعد الإصدار API_LEVEL من حزمة تطوير البرامج (SDK)" بدلاً من ذلك.

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

تحديد التغييرات المفعَّلة باستخدام logcat

لكل تغيير في السلوك، في المرة الأولى التي يطلب فيها تطبيقك واجهة برمجة التطبيقات المتأثرة أثناء عملية تشغيل التطبيق، يُخرج النظام رسالة logcat مثل هذه:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

تتضمّن كل رسالة في logcat المعلومات التالية:

الرقم التعريفي للتغيير

يشير إلى التغيير الذي يؤثر في التطبيق. يتم ربط هذه القيمة بأحد تغييرات السلوك المدرَجة في شاشة تغييرات توافق التطبيق (انظر الشكل 1). في هذا المثال، يتم ربط 194833441 بـ NOTIFICATION_PERM_CHANGE_ID.

الرقم التعريفي الفريد

يشير إلى التطبيق المتأثر بالتغيير.

الولاية

يشير إلى ما إذا كان التغيير يؤثر في التطبيق.

يمكن أن تكون الحالة إحدى القيم التالية:

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

تحديد التغييرات المفعَّلة باستخدام ADB

نفِّذ أمر ADB التالي للاطّلاع على المجموعة الكاملة من التغييرات (المفعَّلة وغير المفعَّلة) على الجهاز بأكمله:

adb shell dumpsys platform_compat

تعرض النتيجة المعلومات التالية لكل تغيير:

الرقم التعريفي للتغيير

معرّف فريد لهذا التغيير في السلوك على سبيل المثال، 194833441.

الاسم

اسم هذا التغيير في السلوك على سبيل المثال، NOTIFICATION_PERM_CHANGE_ID.

معايير targetSDKVersion

‫targetSDKVersion التي يتم حظر التغيير من خلالها (إن وُجدت)

على سبيل المثال، إذا تم تفعيل هذا التغيير فقط للتطبيقات التي تستهدف الإصدار 33 من حزمة تطوير البرامج (SDK) أو الإصدارات الأحدث، يتم عرض enableAfterTargetSdk=32. إذا لم يكن التغيير مقيّدًا من خلال targetSDKVersion، يتم عرض enableAfterTargetSdk=0.

عمليات تجاوز الحِزم

اسم كل حزمة تم فيها إلغاء الحالة التلقائية للتغيير (سواء كانت مفعَّلة أو غير مفعَّلة).

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

packageOverrides={com.my.package=false}

يمكن تفعيل التغييرات التي يتم التحكّم فيها من خلال targetSDKVersion أو إيقافها تلقائيًا، لذا يمكن أن تتضمّن قائمة الحزم حالات لكل من true أو false، وذلك حسب targetSDKVersion لكل تطبيق من هذه التطبيقات. على سبيل المثال:

packageOverrides={com.my.package=true, com.another.package=false}

مزيد من المعلومات عن تغييرات محدّدة

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

• Android 16 (مستوى واجهة برمجة التطبيقات 36)
• ‫Android 15 (مستوى واجهة برمجة التطبيقات 35)
• الإصدار 14 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 34)
• الإصدار 13 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 33)
• ‫Android 12 (مستويات واجهة برمجة التطبيقات 31 و32)
• الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات)

متى يجب تفعيل التغييرات أو إيقافها؟

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

متى يجب إيقاف التغييرات؟

يعتمد قرار إيقاف التغييرات عادةً على ما إذا كان التغيير مقيّدًا من خلال targetSDKVersion أم لا.

تم تفعيل التغييرات لجميع التطبيقات

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

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

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

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

التغييرات التي تم حظرها من قِبل targetSDKVersion

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

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

متى يجب تفعيل التغييرات؟

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

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

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

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

تفعيل التغييرات أو إيقافها

يتيح لك إطار عمل اختبار توافق التطبيقات تفعيل كل تغيير أو إيقافه باستخدام خيارات المطوّرين أو أوامر ADB. بما أنّ تفعيل التغييرات أو إيقافها قد يؤدي إلى تعطُّل تطبيقك أو إيقاف تغييرات الأمان المهمة، هناك بعض القيود على الحالات التي يمكنك فيها تفعيل التغييرات أو إيقافها.

تفعيل التغييرات أو إيقافها باستخدام خيارات المطوّرين

استخدِم خيارات المطوّرين لتفعيل التغييرات أو إيقافها. للعثور على خيارات المطوّرين، اتّبِع الخطوات التالية:

1. إذا لم تكن خيارات المطوّرين مفعَّلة، عليك تفعيلها.
2. افتح تطبيق "الإعدادات" على جهازك وانتقِل إلى النظام > الإعدادات المتقدّمة > خيارات المطوّرين > تغييرات توافق التطبيقات.
3. اختَر تطبيقك من القائمة.
4. من قائمة التغييرات، ابحث عن التغيير الذي تريد تفعيله أو إيقافه وانقر على مفتاح التبديل.

تبديل التغييرات باستخدام ADB

لتفعيل تغيير أو إيقافه باستخدام ADB، نفِّذ أحد الأوامر التالية:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

أدخِل إما CHANGE_ID (على سبيل المثال، 194833441) أو CHANGE_NAME (على سبيل المثال، NOTIFICATION_PERM_CHANGE_ID) وPACKAGE_NAME لتطبيقك.

يمكنك أيضًا استخدام الأمر التالي لإعادة ضبط أحد التغييرات على حالته التلقائية، وإزالة أي إلغاء تم ضبطه باستخدام ADB أو خيارات المطوّرين:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

القيود المفروضة على تفعيل التغييرات أو إيقافها

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

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