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

طرَح نظام Android 11 أدوات جديدة للمطوّرين للاختبار و تصحيح أخطاء تطبيقك مقابل تغييرات السلوك في الإصدارات الأحدث من Android بدون خادم. تُعد هذه الأدوات جزءًا من إطار عمل التوافق الذي يتيح للتطبيق يعمل المطورون على تشغيل التغييرات التي قد تؤدي إلى أعطال أو إيقافها بشكل فردي باستخدام developer أو ADB. يمكنك الاستفادة من هذه المرونة أثناء الاستعداد لاستهداف آخر الأخبار. الإصدار الثابت لواجهة برمجة التطبيقات وأثناء اختبار تطبيقك باستخدام إصدار المعاينة لإصدار Android القادم.

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

كيفية تحديد التغييرات التي تم تفعيلها

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

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

يمكنك معرفة التغييرات التي تم تفعيلها وتفعيل تلك التغييرات أو إيقافها في خيارات مطور الجهاز. للوصول إلى هذه الخيارات، اتبع الخطوات التالية:

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 التي يحصرها التغيير (إن توفّرت).

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

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

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

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