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

قدّمت إصدارات 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.

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

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

الولاية

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

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

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

متى يجب التبديل بين التغييرات؟

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

الحالات التي يجب فيها إيقاف التغييرات التلقائية

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

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

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

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

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

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

التغييرات التي يتم التحكّم فيها من خلال targetSDKVersion

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

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

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

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

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

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

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

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

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

تبديل التغييرات باستخدام خيارات المطوّرين

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

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 أقدم من الإصدار الذي تم فيه إطلاق الميزة. عند تفعيل تغيير أو إيقافه، فإنّك تلغي حالته التلقائية.

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