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

يوفّر نظام التشغيل 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، يحمل هذا القسم عنوان "تم التفعيل بعد حزمة SDK API_LEVEL" بدلاً من ذلك.

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

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

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

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

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

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

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

UID

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

الولاية

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

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

الولاية	المعنى
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 15 (المستوى 35 لواجهة برمجة التطبيقات)
• Android 14 (المستوى 34 لواجهة برمجة التطبيقات)
• Android 13 (المستوى 33 لواجهة برمجة التطبيقات)
• Android 12 (المستوىان 31 و32 لواجهة برمجة التطبيقات)
• Android 11 (المستوى 30 لواجهة برمجة التطبيقات)

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

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

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

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

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

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

على سبيل المثال، إذا كنت تستعد لاستهداف الإصدار 15 من Android (المستوى 35 لواجهة برمجة التطبيقات)، يمكنك البدء بتثبيت تطبيقك على جهاز يعمل بالإصدار 15 من 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 أقل من الإصدار المحدود. عند تفعيل أحد التغييرات أو إيقافه، يتم إلغاء حالته التلقائية.

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