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

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

متى يجب تبديل التغييرات؟

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

متى يجب تبديل التغييرات إلى غير مفعَّلة؟

يعتمد تحديد متى يجب تبديل التغييرات إلى غير مفعَّلة عادةً على ما إذا كان التغيير يتم تقييده حسب targetSDKVersion أم لا.

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

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

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

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

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

التغييرات التي يتم تقييدها حسب targetSDKVersion

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

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

متى يجب تبديل التغييرات إلى مفعَّلة؟

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

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

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

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

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

يتيح لك إطار عمل التوافق تبديل كل تغيير بين مفعَّل وغير مفعَّل باستخدام خيارات المطوّرين أو أوامر ADB. بما أنّ تبديل التغييرات بين مفعَّلة وغير مفعَّلة يمكن أن يؤدي إلى تعطُّل تطبيقك أو إيقاف تغييرات الأمان المهمة، هناك بعض القيود على متى يمكنك تبديل التغييرات.

ملاحظة: في كل مرة تبدّل فيها تغييرًا لتطبيق باستخدام خيارات المطوّرين أو أوامر ADB، سيتم إيقاف التطبيق لضمان سريان عملية الإلغاء على الفور.

تبديل التغييرات باستخدام خيارات المطوّرين

استخدِم خيارات المطوّرين لتبديل التغييرات بين مفعَّلة وغير مفعَّلة. للعثور على خيارات المطوّرين، اتّبِع الخطوات التالية:

1. إذا لم تكن خيارات المطوّرين مفعَّلة، فعِّلها.
2. افتح تطبيق "الإعدادات" على جهازك وانتقِل إلى النظام > خيارات متقدّمة > خيارات المطوّرين > التغييرات في توافق التطبيقات.
3. اختَر تطبيقك من القائمة.
4. من قائمة التغييرات، ابحث عن التغيير الذي تريد تبديله بين مفعَّل وغير مفعَّل وانقر على مفتاح التبديل.

الشكل 2. تبديل التغييرات بين مفعَّلة وغير مفعَّلة

تبديل التغييرات باستخدام 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	جميع التغييرات الأخرى
معاينة المطور أو الإصدار التجريبي	لا يمكن التبديل	يمكن التبديل	يمكن التبديل
إصدار المستخدم العلني	لا يمكن التبديل	يمكن التبديل	لا يمكن التبديل