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

طرَح نظام 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" بدلاً من ذلك.

  ملاحظة: خلال معاينة Android 15 إلى أن يتم الانتهاء من مستوى واجهة برمجة التطبيقات، تستخدم بعض التغييرات التي يتم تفعيلها فقط عند استهداف Android 15 القيمة 10000 لمستوى واجهة برمجة التطبيقات بدلاً من مستوى واجهة برمجة التطبيقات النهائي المفترَض أن يكون 35.

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

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

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

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

ملاحظة: يتم تسجيل كل تغيير مرة واحدة كحد أقصى لكل عملية. يمكنك فرض إيقاف عملية تطبيقك وإعادة تشغيلها لضمان الاطّلاع على جميع رسائل Logcat ذات الصلة.

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

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

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

التغييرات التي يتم حفظها من قِبل "targetSDKVersion"

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

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

حالات تفعيل التغييرات

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

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

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

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

يتيح لك إطار عمل التوافق التبديل بين تفعيل كل تغيير أو إيقافه باستخدام خيارات المطوّرين أو أوامر 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 أقدم من الإصدار المقفل. عند التبديل بين تشغيل أو إيقاف تغيير ما، يتم إلغاء حالته الافتراضية.

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

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