طرَح نظام Android 11 أدوات جديدة للمطوّرين لاختبار تطبيقك وتصحيح الأخطاء فيه لمقارنته بالتغييرات في السلوك في الإصدارات الأحدث من نظام Android الأساسي. هذه الأدوات هي جزء من إطار عمل التوافق الذي يتيح لمطوّري التطبيقات تفعيل التغييرات العاجلة أو إيقافها بشكلٍ فردي باستخدام خيارات المطوّرين أو ADB. يمكنك الاستفادة من هذه المرونة أثناء الاستعداد لاستهداف أحدث إصدار ثابت من واجهة برمجة التطبيقات وأثناء اختبار تطبيقك باستخدام إصدار المعاينة من إصدار Android التالي.
عند استخدام أدوات إطار عمل التوافق، يتكيّف نظام Android الأساسي
تلقائيًا مع منطقه الداخلي، كي لا تحتاج إلى تغيير
targetSDKVersion
أو إعادة تحويل تطبيقك برمجيًا من أجل إجراء الاختبار الأساسي. ولأنّ التغييرات قابلة للتبديل بشكل فردي، يمكنك عزل تغيير واحد في السلوك واختباره وتصحيحه في كل مرة أو إيقاف تغيير واحد يتسبب في حدوث مشاكل إذا كنت بحاجة إلى اختبار شيء آخر أولاً.
كيفية تحديد التغييرات التي تم تفعيلها
عند تفعيل تغيير السلوك، يمكن أن يؤثر ذلك في طريقة وصول تطبيقك إلى واجهات برمجة تطبيقات النظام الأساسي التي تأثّرت بهذا التغيير. يمكنك التحقّق من تغييرات السلوك التي يتم تفعيلها باستخدام خيارات المطوّرين أو أوامر Logcat أو ADB.
تحديد التغييرات المفعَّلة باستخدام خيارات المطوّرين
![](https://developer.android.com/static/images/guide/app-compatibility/appcompat-dev-options.png?authuser=8&hl=ar)
الشكل 1. تغييرات توافق التطبيق في خيارات المطورين.
يمكنك معرفة التغييرات التي تم تفعيلها وتفعيل تلك التغييرات أو إيقافها في خيارات المطوّرين على الجهاز. للوصول إلى هذه الخيارات، اتبع الخطوات التالية:
- إذا لم يتم تفعيل خيارات المطوّرين من قبل، يجب تفعيلها.
- افتح تطبيق "الإعدادات" على جهازك وانتقِل إلى النظام > الإعدادات المتقدّمة > خيارات المطوّرين > التغييرات في توافق التطبيقات.
اختَر تطبيقك من القائمة.
ينتمي كل تغيير في السلوك عادةً إلى إحدى الفئتين التاليتين:
التغييرات التي تؤثر في جميع التطبيقات التي تعمل على هذا الإصدار من 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 14 (المستوى 34 لواجهة برمجة التطبيقات)، يمكنك البدء بتثبيت تطبيقك على جهاز يعمل بالإصدار 14 من نظام التشغيل Android واختبار تطبيقك باستخدام خطوات عمل الاختبار المعتادة. إذا واجه تطبيقك مشاكل، يمكنك إيقاف التغيير الذي يسبّب المشكلة حتى تتمكّن من مواصلة إجراء الاختبارات بحثًا عن المشاكل الأخرى.
ولأنّ هذه التغييرات يمكن أن تؤثر في جميع التطبيقات بغض النظر عن
targetSDKVersion
، عليك عادةً اختبار تطبيقك وتحديثه بحثًا عن هذه التغييرات قبل إجراء التغييرات التي يتم حظرها فيtargetSDKVersion
. يساعد ذلك في ضمان عدم حصول المستخدمين على تجربة تطبيق متدنية عند تحديث أجهزتهم إلى إصدار نظام أساسي جديد.يجب أيضًا منح الأولوية لاختبار هذه التغييرات لأنّه لا يمكنك إيقاف هذه التغييرات عند استخدام إصدار متاح للجميع من Android. ومن الناحية المثالية، يجب إجراء اختبار لهذه التغييرات لكل إصدار من إصدارات Android أثناء معاينة هذا الإصدار.
- التغييرات التي يتم حفظها من قِبل "
targetSDKVersion
" إذا كان تطبيقك يستهدف فئة
targetSDKVersion
محدّدة، يتم تلقائيًا تفعيل أي تغييرات يحظرها هذا الإصدار. عند تبديلtargetSDKVersion
لتطبيقك إلى إصدار جديد، سيبدأ الكثير من التغييرات الجديدة في تطبيقك في آنٍ واحد.ولأنّ تطبيقك قد يتأثر بأكثر من تغيير واحد من هذه التغييرات، قد تحتاج إلى إيقاف بعض هذه التغييرات بشكلٍ فردي أثناء اختبار تطبيقك وتصحيح الأخطاء فيه.
حالات تفعيل التغييرات
يتم تلقائيًا إيقاف التغييرات المرتبطة بسياسة targetSDKVersion
محدّدة
عندما يستهدف أحد التطبيقات إصدارًا أقل من حزمة تطوير البرامج (SDK) مقارنةً بالإصدار المحدود.
عادةً، أثناء الاستعداد لاستهداف targetSdkVersion
جديد، سيكون لديك قائمة
بالتغييرات في السلوك التي يجب اختبار تطبيقك وتصحيح الأخطاء فيها.
على سبيل المثال، قد تختبر تطبيقك باستخدام سلسلة من التغييرات على النظام الأساسي
خلال targetSdkVersion
التالي. باستخدام خيارات المطوّرين أو أوامر ADB، يمكنك
تفعيل واختبار كل تغيير محصور واحدًا تلو الآخر، بدلاً من تغيير
بيان التطبيق والموافقة على كل تغيير دفعة واحدة. ويمكن أن يساعدك عنصر التحكّم الإضافي هذا في اختبار التغييرات بمعزل عن التطبيقات وتجنُّب تصحيح أخطاء أجزاء متعددة من تطبيقك وتحديثها في آنٍ واحد.
بعد تفعيل أحد التغييرات، يمكنك اختبار تطبيقك وتصحيح الأخطاء فيه باستخدام مهام سير عمل الاختبار المعتادة. إذا واجهت مشكلات، فتحقق من سجلاتك للمساعدة في تحديد سبب المشكلة. إذا لم يكن واضحًا ما إذا كانت المشكلة ناتجة عن تغيير في النظام الأساسي مفعَّل، جرّب إيقاف هذا التغيير ثم إعادة اختبار تلك المنطقة في تطبيقك.
تفعيل التغييرات أو إيقافها
يتيح لك إطار عمل التوافق التبديل بين تفعيل كل تغيير أو إيقافه باستخدام خيارات المطوّرين أو أوامر ADB. ولأنّ تفعيل التغييرات أو إيقافها قد يؤدي إلى تعطُّل تطبيقك أو إيقاف تغييرات أمان مهمّة، هناك بعض القيود على وقت التبديل بين التغييرات.
تبديل التغييرات باستخدام خيارات المطوّرين
استخدِم خيارات المطوّرين لتفعيل التغييرات أو إيقافها. وللعثور على خيارات المطوّرين، اتّبِع الخطوات التالية:
- إذا لم يتم تفعيل خيارات المطوّرين من قبل، يجب تفعيلها.
- افتح تطبيق "الإعدادات" على جهازك وانتقِل إلى النظام > الإعدادات المتقدّمة > خيارات المطوّرين > التغييرات في توافق التطبيقات.
- اختَر تطبيقك من القائمة.
من قائمة التغييرات، ابحث عن التغيير الذي تريد تفعيله أو إيقافه وانقر على مفتاح التبديل.
تبديل التغييرات باستخدام 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 | جميع التغييرات الأخرى | |
معاينة المطوّر أو الإصدار التجريبي | تعذّر التبديل | إمكانية التبديل | إمكانية التبديل |
تصميم المستخدم العلني | تعذّر التبديل | إمكانية التبديل | تعذّر التبديل |