القيود المفروضة على الواجهات غير المتوفرة في حزمة SDK

بدءًا من الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات)، تفرض المنصة قيودًا على واجهات برمجة التطبيقات غير التابعة لحزمة SDK التي يمكن لتطبيقك استخدامها. يتم تطبيق هذه القيود عندما يشير تطبيق إلى واجهة غير متوفرة في حزمة SDK أو يحاول الحصول على معرّفها باستخدام الانعكاس أو JNI. تم وضع هذه القيود للمساعدة في تحسين تجربة المستخدمين والمطوّرين والحد من مخاطر الأعطال التي يواجهها المستخدمون وعمليات الطرح الطارئة التي يجريها المطوّرون. لمزيد من المعلومات حول هذا القرار، يُرجى الاطّلاع على مقالة تحسين الثبات من خلال تقليل استخدام الواجهات غير المتوفّرة في حزمة SDK.

التمييز بين الواجهات المتوفّرة في حزمة SDK والواجهات غير المتوفّرة في حزمة SDK

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

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

قوائم واجهات برمجة التطبيقات غير المتوفّرة في حِزمة تطوير البرامج (SDK)

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

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

قائمة علامات الرمز البرمجي الوصف
القائمة المحظورة
  • blocked
  • تم إيقافها نهائيًا: blacklist
 واجهات غير متوفرة في حزمة SDK ولا يمكنك استخدامها بغض النظر عن مستوى واجهة برمجة التطبيقات المستهدَف في تطبيقك إذا حاول تطبيقك الوصول إلى إحدى هذه الواجهات، سيؤدي النظام إلى عرض خطأ.
محظورة بشروط
  • max-target-x
  • تم إيقافها نهائيًا: greylist-max-x

بدءًا من Android 9 (المستوى 28 لواجهة برمجة التطبيقات)، يتضمّن كل مستوى لواجهة برمجة التطبيقات واجهات غير تابعة لحزمة SDK تكون محظورة عندما يستهدف التطبيق هذا المستوى.

يتم تصنيف هذه القوائم حسب الحد الأقصى لمستوى واجهة برمجة التطبيقات (max-target-x) الذي يمكن أن يستهدفه التطبيق قبل أن يتعذّر عليه الوصول إلى الواجهات غير التابعة لحزمة SDK في تلك القائمة. على سبيل المثال، واجهة غير تابعة لحزمة SDK لم يتم حظرها في Android Pie ولكن تم حظرها الآن في Android 10، هي جزء من القائمة max-target-p (greylist-max-p)، حيث يشير الحرف "p" إلى Pie أو Android 9 (المستوى 28 من واجهة برمجة التطبيقات).

إذا حاول تطبيقك الوصول إلى واجهة مقيَّدة بمستوى واجهة برمجة التطبيقات المستهدَف، سيتعامل النظام معها كما لو كانت جزءًا من قائمة الحظر.
غير متوافق
  • unsupported
  • تم إيقافها نهائيًا: greylist
 واجهات غير متوفرة في حزمة SDK وغير مقيّدة ويمكن لتطبيقك استخدامها يُرجى العِلم أنّ هذه الواجهات غير متوافقة وقد تتغيّر بدون إشعار. نتوقّع أن يتم حظر هذه الواجهات بشكل مشروط في إصدارات Android المستقبلية ضمن قائمة max-target-x.
SDK
  • كلا الجهازَين public-api وsdk
  • متوقّف نهائيًا: كلّ من public-api وwhitelist
 واجهات يمكن استخدامها بحرية وهي متاحة الآن كجزء من فهرس الحِزم في إطار عمل Android الموثّق رسميًا.
واجهات برمجة التطبيقات الاختبارية
  • test-api
 واجهات تُستخدَم لاختبار النظام الداخلي، مثل واجهات برمجة التطبيقات التي تسهّل الاختبار من خلال مجموعة أدوات اختبار التوافق (CTS) لا تشكّل واجهات برمجة التطبيقات الاختبارية جزءًا من حزمة تطوير البرامج (SDK). اعتبارًا من Android 11 (المستوى 30 لواجهة برمجة التطبيقات)، يتم تضمين واجهات برمجة التطبيقات التجريبية في قائمة الحظر، وبالتالي لا يُسمح للتطبيقات باستخدامها بغض النظر عن مستوى واجهة برمجة التطبيقات المستهدَف. جميع واجهات برمجة التطبيقات التجريبية غير متوافقة وقد تتغيّر بدون إشعار، بغض النظر عن مستوى واجهة برمجة التطبيقات للمنصة.

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

تحديد القائمة التي تنتمي إليها الواجهة

يتم إنشاء قوائم الواجهات غير المتوفرة في حزمة SDK كجزء من النظام الأساسي. اطّلِع على الأقسام التالية للحصول على معلومات حول كل إصدار من إصدارات Android.

Android 16

بالنسبة إلى نظام التشغيل Android 16 (المستوى 36 من واجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يصف جميع الواجهات غير التابعة لحزمة SDK والقوائم الخاصة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

لمزيد من المعلومات حول التغييرات في قائمة واجهات برمجة التطبيقات غير التابعة لحزمة SDK في Android 16، راجِع تعديلات على القيود المفروضة على واجهات برمجة التطبيقات غير التابعة لحزمة SDK في Android 16.

Android 15

بالنسبة إلى نظام التشغيل Android 15 (المستوى 35 من واجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع الواجهات غير التابعة لحزمة SDK والقوائم الخاصة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

لمزيد من المعلومات حول التغييرات في قائمة واجهات برمجة التطبيقات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 15، يمكنك الاطّلاع على تعديلات على قيود الواجهات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 15.

Android 14

في نظام التشغيل Android 14 (المستوى 34 من واجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع الواجهات غير التابعة لحزمة SDK والقوائم المرتبطة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

لمزيد من المعلومات عن التغييرات في قائمة واجهات برمجة التطبيقات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 14، يُرجى الاطّلاع على تعديلات على قيود واجهات برمجة التطبيقات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 14.

Android 13

بالنسبة إلى نظام التشغيل Android 13 (المستوى 33 لواجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع واجهات برمجة التطبيقات غير التابعة لحزمة SDK والقوائم المقابلة لها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

لمزيد من المعلومات حول التغييرات التي طرأت على قائمة واجهات برمجة التطبيقات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 13، بما في ذلك بدائل واجهات برمجة التطبيقات العامة المقترَحة لواجهات برمجة التطبيقات التي يتم حظرها بشكل مشروط في نظام التشغيل Android 13، يمكنك الاطّلاع على تعديلات على القيود المفروضة على الواجهات غير المتوفّرة في حِزمة تطوير البرامج (SDK) في نظام التشغيل Android 13.

Android 12

في نظام التشغيل Android 12 (المستوى 31 لواجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع الواجهات غير التابعة لحزمة SDK والقوائم الخاصة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

لمزيد من المعلومات حول التغييرات في قائمة واجهات برمجة التطبيقات غير التابعة لحزمة SDK في نظام التشغيل Android 12، بما في ذلك بدائل واجهات برمجة التطبيقات العامة المقترَحة لواجهات برمجة التطبيقات التي يتم حظرها بشكل مشروط في نظام التشغيل Android 12، يُرجى الاطّلاع على التغييرات في القائمة لنظام التشغيل Android 12.

Android 11

بالنسبة إلى الإصدار Android 11 (المستوى 30 لواجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع الواجهات غير التابعة لحزمة SDK والقوائم الخاصة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

لمزيد من المعلومات حول التغييرات في قائمة واجهات برمجة التطبيقات غير التابعة لحزمة SDK في نظام التشغيل Android 11، بما في ذلك بدائل واجهات برمجة التطبيقات العامة المقترَحة لواجهات برمجة التطبيقات التي يتم حظرها بشكل مشروط في نظام التشغيل Android 11، يُرجى الاطّلاع على التغييرات في القائمة لنظام التشغيل Android 11.

Android 10

بالنسبة إلى نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، يمكنك تنزيل الملف التالي الذي يوضّح جميع الواجهات غير التابعة لحزمة SDK والقوائم الخاصة بها:

الملف: hiddenapi-flags.csv

مجموع التحقّق SHA-256: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

لمزيد من المعلومات حول التغييرات في قائمة واجهات برمجة التطبيقات غير التابعة لحزمة SDK في Android 10، بما في ذلك بدائل واجهات برمجة التطبيقات العامة المقترَحة لواجهات برمجة التطبيقات التي يتم حظرها بشكل مشروط في Android 10، يُرجى الاطّلاع على التغييرات في القائمة لنظام التشغيل Android 10.

Android 9

في نظام التشغيل Android 9 (المستوى 28 من واجهة برمجة التطبيقات)، يحتوي ملف النص التالي على قائمة بواجهات برمجة التطبيقات غير التابعة لحزمة SDK والتي لا تخضع لقيود (المدرَجة في القائمة الرمادية): hiddenapi-light-greylist.txt.

يتم إنشاء القائمة المحظورة (blacklist) وقائمة واجهات برمجة التطبيقات المحظورة بشكل مشروط (القائمة الرمادية الداكنة) في وقت الإنشاء.

إنشاء قوائم من AOSP

عند العمل باستخدام AOSP، يمكنك إنشاء ملف hiddenapi-flags.csv يحتوي على جميع الواجهات غير المتوفرة في حزمة SDK والقوائم الخاصة بها. لإجراء ذلك، عليك تنزيل رمز مصدر AOSP ثم تنفيذ الأمر التالي:

m out/soong/hiddenapi/hiddenapi-flags.csv

يمكنك بعد ذلك العثور على الملف في الموقع التالي:

out/soong/hiddenapi/hiddenapi-flags.csv

السلوك المتوقّع عند الوصول إلى واجهات غير متوفرة في حزمة SDK ومحظورة

يوضِّح الجدول التالي السلوك المتوقّع إذا حاول تطبيقك الوصول إلى واجهة غير متوفرة في SDK ومدرَجة في قائمة الحظر.

وسائل الوصول النتيجة
تعليمات Dalvik تشير إلى حقل تم طرح NoSuchFieldError
تعليمات Dalvik تشير إلى طريقة تم طرح NoSuchMethodError
الانعكاس باستخدام Class.getDeclaredField() أو Class.getField() تم طرح NoSuchFieldException
الانعكاس باستخدام Class.getDeclaredMethod() وClass.getMethod() تم طرح NoSuchMethodException
الانعكاس باستخدام Class.getDeclaredFields() وClass.getFields() عدم ظهور أعضاء غير مشتركين في حزمة SDK ضمن النتائج
الانعكاس باستخدام Class.getDeclaredMethods() وClass.getMethods() عدم ظهور أعضاء غير مشتركين في حزمة SDK ضمن النتائج
JNI باستخدام env->GetFieldID() تم إرجاع NULL، وتم طرح NoSuchFieldError
JNI باستخدام env->GetMethodID() تم إرجاع NULL، وتم طرح NoSuchMethodError

اختبار تطبيقك بحثًا عن واجهات غير متوفرة في حزمة SDK

تتوفّر عدة طرق يمكنك استخدامها لاختبار الواجهات غير المتوفرة في حزمة SDK في تطبيقك.

الاختبار باستخدام تطبيق يمكن تصحيحه

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

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

  • فئة التعريف والاسم والنوع (بالتنسيق الذي يستخدمه وقت تشغيل Android)
  • وسيلة الوصول: إما الربط أو استخدام الانعكاس أو استخدام JNI
  • القائمة التي تنتمي إليها الواجهة غير المتوفرة في حزمة SDK

يمكنك استخدام adb logcat للوصول إلى رسائل السجلّ هذه التي تظهر ضمن معرّف العملية (PID) للتطبيق قيد التشغيل. على سبيل المثال، قد يظهر إدخال في السجلّ على النحو التالي:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

الاختبار باستخدام واجهة برمجة التطبيقات StrictMode

يمكنك أيضًا اختبار الواجهات غير المتوفرة في حزمة SDK باستخدام واجهة برمجة التطبيقات StrictMode. استخدِم طريقة detectNonSdkApiUsage لتفعيل هذه الميزة. بعد تفعيل واجهة برمجة التطبيقات StrictMode، يمكنك تلقّي ردّ الاتصال لكل استخدام لواجهة غير متوفرة في حزمة SDK من خلال استخدام penaltyListener، حيث يمكنك تنفيذ معالجة مخصّصة. يتم استخلاص الكائن Violation المقدَّم في دالة الرجوع من Throwable، ويوفّر تتبُّع تسلسل استدعاء الدوال البرمجية المضمّن سياق الاستخدام.

الاختبار باستخدام أداة veridex

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

تشمل قيود أداة veridex ما يلي:

  • لا يمكنه رصد عمليات الاستدعاء من خلال JNI.
  • يمكنه رصد مجموعة فرعية فقط من عمليات الاستدعاء من خلال الانعكاس.
  • يقتصر تحليل مسارات الرموز غير النشطة على عمليات التحقّق من مستوى واجهة برمجة التطبيقات.
  • لا يمكن تشغيله إلا على الأجهزة التي تتوافق مع تعليمات SSE4.2 وPOPCNT.

نظام التشغيل Windows

لا يتم توفير ملفات ثنائية أصلية لنظام التشغيل Windows، ولكن يمكنك تشغيل أداة veridex على نظام التشغيل Windows من خلال تنفيذ الملفات الثنائية لنظام التشغيل Linux باستخدام "نظام Windows الفرعي على Linux" (WSL). قبل اتّباع الخطوات الواردة في هذا القسم، عليك تثبيت نظام WSL واختيار Ubuntu كتوزيعة Linux.

بعد تثبيت Ubuntu، افتح نافذة طرفية في Ubuntu ثم اتّبِع الخطوات التالية:

  1. نزِّل أداة veridex من مستودع الإصدارات المسبقة المضمّنة في وقت تشغيل Android.
  2. استخرِج محتوى الملف appcompat.tar.gz.
  3. في المجلد الذي تم استخراجه، ابحث عن الملف veridex-linux.zip واستخرِجه.

  4. انتقِل إلى المجلد الذي تم فك ضغطه، ثم نفِّذ الأمر التالي، حيث يمثّل your-app.apk حزمة APK التي تريد اختبارها:

    ./appcompat.sh --dex-file=your-app.apk

نظام التشغيل Mac

لتشغيل أداة veridex على جهاز macOS، اتّبِع الخطوات التالية:

  1. نزِّل أداة veridex من مستودع الإصدارات المسبقة المضمّنة في وقت تشغيل Android.
  2. استخرِج محتوى الملف appcompat.tar.gz.
  3. في المجلد الذي تم استخراجه، ابحث عن الملف veridex-mac.zip واستخرِجه.

  4. انتقِل إلى المجلد الذي تم فك ضغطه، ثم نفِّذ الأمر التالي، حيث يمثّل /path-from-root/your-app.apk مسار حزمة APK التي تريد اختبارها، بدءًا من الدليل الجذر لنظامك:

    ./appcompat.sh --dex-file=/path-from-root/your-app.apk

Linux

لتشغيل أداة veridex على نظام التشغيل Linux، اتّبِع الخطوات التالية:

  1. نزِّل أداة veridex من مستودع الإصدارات المسبقة المضمّنة في وقت تشغيل Android.
  2. استخرِج محتوى الملف appcompat.tar.gz.
  3. في المجلد الذي تم استخراجه، ابحث عن الملف veridex-linux.zip واستخرِجه.

  4. انتقِل إلى المجلد الذي تم فك ضغطه، ثم نفِّذ الأمر التالي، حيث يمثّل your-app.apk حزمة APK التي تريد اختبارها:

    ./appcompat.sh --dex-file=your-app.apk

الاختبار باستخدام أداة lint في "استوديو Android"

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

يمكنك أيضًا تشغيل أداة lint من سطر الأوامر أو تشغيل عمليات الفحص يدويًا على مشروع أو مجلد أو ملف معيّن.

الاختبار باستخدام Play Console

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

لمزيد من المعلومات، راجِع قسم "التوافق مع Android" في مقالة استخدام تقارير الإطلاق التجريبي لتحديد المشاكل.

طلب واجهة برمجة تطبيقات عامة جديدة

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

عند إنشاء طلب ميزة، يُرجى تقديم المعلومات التالية:

  • واجهة برمجة التطبيقات غير المتوافقة التي تستخدمها، بما في ذلك الواصف الكامل الذي يظهر في رسالة logcat Accessing hidden ...
  • سبب حاجتك إلى استخدام واجهات برمجة التطبيقات هذه، بما في ذلك تفاصيل حول الميزة ذات المستوى العالي التي تحتاج إلى واجهة برمجة التطبيقات، وليس مجرد تفاصيل منخفضة المستوى
  • توضيح سبب عدم كفاية أي واجهات برمجة تطبيقات ذات صلة بحزمة تطوير البرامج (SDK) العامة لأغراضك
  • أي حلول بديلة أخرى جرّبتها وسبب عدم نجاحها

عند تقديم هذه التفاصيل في طلب الميزة، تزيد من احتمالية الموافقة على توفير واجهة برمجة تطبيقات عامة جديدة.

أسئلة أخرى

يتضمّن هذا القسم بعض الإجابات عن الأسئلة الأخرى التي يطرحها المطوّرون بشكل متكرّر:

أسئلة عامة

كيف يمكن لشركة Google التأكّد من أنّها تستطيع رصد احتياجات جميع التطبيقات من خلال أداة تتبُّع المشاكل؟

أنشأنا القوائم الأولية لنظام التشغيل Android 9 (المستوى 28 لواجهة برمجة التطبيقات) من خلال تحليل ثابت للتطبيقات تم استكماله باستخدام الطرق التالية:

  • الاختبار اليدوي لأهم التطبيقات على Play وخارجه
  • التقارير الداخلية
  • جمع البيانات تلقائيًا من المستخدمين الداخليين
  • تقارير معاينة المطوّرين
  • تحليل ثابت إضافي مصمّم ليشمل بشكل متحفّظ المزيد من النتائج الإيجابية الخاطئة

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

كيف يمكنني تفعيل الوصول إلى واجهات غير متوفرة في حزمة SDK؟

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

الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) أو إصدار أحدث

لتفعيل إمكانية الوصول، استخدِم الأمر التالي في adb

الأمر:

adb shell settings put global hidden_api_policy  1

لإعادة ضبط سياسة فرض استخدام واجهة برمجة التطبيقات على الإعدادات التلقائية، استخدِم الأمر التالي:

adb shell settings delete global hidden_api_policy
‫Android 9 (المستوى 28 لواجهة برمجة التطبيقات)

لتفعيل إمكانية الوصول، استخدِم أوامر adb التالية:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

لإعادة ضبط سياسة فرض استخدام واجهة برمجة التطبيقات على الإعدادات التلقائية، استخدِم الأوامر التالية:

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

يمكنك ضبط العدد الصحيح في سياسة فرض استخدام واجهة برمجة التطبيقات على إحدى القيم التالية:

  • ‫0: لإيقاف جميع عمليات رصد الواجهات غير المتوفرة في حزمة SDK يؤدي استخدام هذا الإعداد إلى إيقاف جميع رسائل السجل المتعلقة باستخدام واجهات غير متوفرة في حزمة SDK، كما يمنعك من اختبار تطبيقك باستخدام واجهة StrictMode API. لا يُنصح باستخدام هذا الإعداد.
  • ‫1: تفعيل إمكانية الوصول إلى جميع الواجهات غير المتوفرة في حزمة SDK، ولكن طباعة رسائل السجل مع تحذيرات بشأن أي استخدام لواجهة غير متوفرة في حزمة SDK يتيح لك استخدام هذا الإعداد أيضًا اختبار تطبيقك باستخدام واجهة برمجة التطبيقات StrictMode.
  • ‫2: عدم السماح باستخدام واجهات غير متوفرة في حزمة SDK تنتمي إلى قائمة الحظر أو يتم حظرها بشكل مشروط لمستوى واجهة برمجة التطبيقات المستهدَف

أسئلة حول قوائم الواجهات غير المتوفرة في حزمة SDK

أين يمكنني العثور على قوائم واجهات برمجة التطبيقات غير التابعة لحزمة تطوير البرامج (SDK) في صورة النظام؟

يتم ترميزها في وحدات بت علامات الوصول إلى الحقول والطُرق في ملفات dex الخاصة بالنظام الأساسي. لا يتوفّر ملف منفصل في صورة النظام يحتوي على هذه القوائم.

هل قوائم واجهات برمجة التطبيقات غير التابعة لحزمة SDK هي نفسها على أجهزة مصنّعين مختلفين للأجهزة الأصلية (OEM) التي تعمل بإصدارات Android نفسها؟

يمكن لمصنّعي المعدات الأصلية إضافة واجهاتهم الخاصة إلى قائمة الحظر (القائمة السوداء)، ولكن لا يمكنهم إزالة واجهات من قوائم واجهات برمجة التطبيقات غير التابعة للحزمة SDK في AOSP. يمنع مستند تعريف التوافق إجراء مثل هذه التغييرات، وتضمن اختبارات CTS أنّ "وقت تشغيل Android" يفرض القائمة.

هل هناك أي قيود على واجهات برمجة التطبيقات غير التابعة لحزمة تطوير البرامج الأصلية (NDK) في الرمز البرمجي الأصلي؟

تتضمّن حزمة تطوير البرامج (SDK) لنظام التشغيل Android واجهات Java. بدأت المنصة في تقييد الوصول إلى واجهات غير تابعة لمجموعة أدوات تطوير البرامج الأصلية (NDK) لرموز C/C++ البرمجية الأصلية في نظام التشغيل Android 7 (المستوى 26 من واجهة برمجة التطبيقات). لمزيد من المعلومات، يُرجى الاطّلاع على تحسين الثبات من خلال قيود رموز C/C++ الخاصة في نظام التشغيل Android N.

هل هناك أي خطة لفرض قيود على dex2oat أو التعديل على ملفات DEX؟

ليس لدينا خطط نشطة لحظر الوصول إلى ملف dex2oat الثنائي، ولكننا لا ننوي أن يكون تنسيق ملف DEX ثابتًا أو واجهة عامة تتجاوز الأجزاء المحدّدة علنًا في تنسيق Dalvik Executable. نحتفظ بالحق في تعديل أو إزالة dex2oat والأجزاء غير المحدّدة من تنسيق DEX في أي وقت. يُرجى أيضًا العِلم أنّ الملفات المشتقة التي ينتجها dex2oat، مثل ODEX (المعروف أيضًا باسم OAT) وVDEX وCDEX، هي جميعًا بتنسيقات غير محددة.

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

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

هل تنطبق قيود الواجهات غير التابعة لحِزم تطوير البرامج (SDK) على جميع التطبيقات، بما في ذلك تطبيقات النظام والتطبيقات المحلية، وليس فقط تطبيقات الجهات الخارجية؟

نعم، ولكننا نستثني التطبيقات الموقَّعة باستخدام مفتاح النظام الأساسي وبعض تطبيقات صور النظام. يُرجى العِلم أنّ هذه الاستثناءات تنطبق فقط على التطبيقات التي تشكّل جزءًا من صورة النظام (أو تطبيقات صورة النظام المُحدَّثة). القائمة مخصّصة فقط للتطبيقات التي تستخدم واجهات برمجة التطبيقات الخاصة بالمنصة، وليس واجهات برمجة التطبيقات الخاصة بحزمة تطوير البرامج (SDK) (حيث LOCAL_PRIVATE_PLATFORM_APIS := true).