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

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

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

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

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

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

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

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

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

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

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

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

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

    ويتم تفعيل هذه التغييرات تلقائيًا في إطار عمل التوافق إذا كان تطبيقك يستهدف إصدارًا أعلى من إصدار واجهة برمجة التطبيقات المدرَج. على سبيل المثال، التغيير في السلوك الذي يتم تسجيله بواسطة targetSDKVersion في نظام التشغيل Android 11 (المستوى 30 لواجهة برمجة التطبيقات) سيتم إدراجه في واجهة المستخدم في القسم Enabled After SDK 29 (يظهر أيضًا على أنّه مفعّل لـ targetSdkVersion >=30).

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

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

بالنسبة إلى كل تغيير في السلوك، في المرة الأولى أثناء عملية تطبيقك عندما يستدعي تطبيقك واجهة برمجة التطبيقات المتأثرة، يعرض النظام رسالة Logcat مثل هذه:

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

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

الرقم التعريفي للتغيير
تشير إلى التغيير الذي يؤثر في التطبيق. وتُشير هذه القيمة إلى أحد تغييرات السلوك الواردة في شاشة تغييرات توافق التطبيق (راجِع الشكل 1). في هذا المثال، يتم ربط 119147584 بـ CALLBACK_ON_CLEAR_CHANGE.
المعرّف الفريد
يشير إلى التطبيق المتأثر بالتغيير.
الولاية

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

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

الولاية المعنى
ENABLED التغيير مفعّل حاليًا وسيؤثر في سلوك التطبيق إذا كان يستخدم واجهات برمجة التطبيقات التي تم تغييرها.
DISABLED

تم إيقاف التغيير حاليًا ولن يؤثر في التطبيق.

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

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

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

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

adb shell dumpsys platform_compat

تسرد المخرجات المعلومات التالية لكل تغيير:

الرقم التعريفي للتغيير
معرّف فريد لهذا التغيير في السلوك مثلاً: 119147584
الاسم
اسم هذا التغيير في السلوك. مثلاً، CALLBACK_ON_CLEAR_CHANGE.
معايير targetSDKVersion

ما targetSDKVersion الذي يتم إجراء التغيير عليه (إذا كان ذلك منطبقًا).

على سبيل المثال، إذا تم تفعيل هذا التغيير فقط للتطبيقات التي تستهدف الإصدار 30 من حزمة SDK أو الإصدارات الأحدث، سيتم عرض enableAfterTargetSdk=29 في الناتج. إذا لم يتم حظر التغيير بواسطة 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. يوضِّح هذا القسم بعض الاستراتيجيات التي يمكنك استخدامها لتحديد وقت تفعيل التغييرات أو إيقافها أثناء اختبار تطبيقك وتصحيح الأخطاء فيه.

حالات إيقاف/تفعيل التغييرات

عادةً ما يعتمد تحديد وقت إيقاف التغييرات على ما إذا كان التغيير قد تم بواباته بموجب سياسة targetSDKVersion أم لا.

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

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

على سبيل المثال، إذا كنت تستعد لاستهداف الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات)، يمكنك البدء بتثبيت تطبيقك على جهاز يعمل بالإصدار 14 من نظام التشغيل 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 (على سبيل المثال، 119147584) أو CHANGE_NAME (على سبيل المثال، CALLBACK_ON_CLEAR_CHANGE) وعلامة PACKAGE_NAME الخاصة بتطبيقك.

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

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

القيود المفروضة على تبديل التغييرات

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

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

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