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

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

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

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

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

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

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

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

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

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

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