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

قدّمت منصة 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.

حالات تجاوز الحزمة

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

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

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