اقتراح تصميم إمكانية العرض في وقت تشغيل حزمة تطوير البرامج (SDK)

لا يمكن لحِزم SDK لعرض الإعلانات في "وقت تشغيل SDK" الوصول إلى التدرّج الهرمي للملفات الشخصية للناشر. وبدلاً من ذلك، يكون لحِزم SDK في وقت التشغيل طرق عرض خاصة بها. لا يمكن لحزمة تطوير البرامج (SDK) استخدام واجهات View API نفسها التي تستخدمها خارج وقت تشغيل SDK لتحديد ما إذا كان الإعلان مرئيًا للمستخدم، لأنّ عرض الإعلان غير مرتبط بنافذة التطبيق. ويشمل ذلك واجهات برمجة التطبيقات لعرض Android، مثل getLocationOnScreen أو getLocationInWindow أو getVisibility، والتي لا تعرض القيم المتوقّعة.

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

الإمكانات

يهدف هذا التصميم إلى دعم حِزم SDK لعرض الإعلانات أو شركاء القياس من أجل احتساب بيانات إمكانية العرض التالية (الأسماء مؤقتة وتخضع للتغيير):

نظرة عامة على إمكانية عرض وقت تشغيل حزمة تطوير البرامج (SDK)

• viewport [Rect]: تمثل شاشة الجهاز أو شكل نافذة التطبيق الهندسي، استنادًا إلى إمكانات النظام الأساسي.
• uiContainerGeometry [Rect]: الشكل الهندسي للسمة SandboxedSdkView التي يتم عرضها.
• alpha [float]: تعتيم SandboxedSdkView الذي يتم عرضه.
• onScreenGeometry [Rect]: المجموعة الفرعية من uiContainerGeometry التي لا يتم اقتطاعها حسب مشاهدات الوالدَين، بما يصل إلى viewport.
• occludedGeometry [Rect]: أجزاء onScreenGeometry التي يتم حجبها من خلال أي طرق عرض في التدرج الهرمي للتطبيق. يتضمّن Rect لكل فاصل، يقابل صفر أو واحد أو أكثر من مشاهدات التطبيق التي تتقاطع مع SandboxedSdkView onScreenGeometry

المتطلّبات

• يتم التعبير عن قيم uiContainerGeometry وonScreenGeometry وoccludedGeometry في المساحة الإحداثية لـ viewport.
• يتم إعداد تقارير تغيير إذن الوصول بأقلّ وقت استجابة.
• يمكن قياس مستوى الرؤية على مدار دورة الحياة الكاملة لمشاهدة الإعلان، من أول ظهور له حتى آخر مرة.

اقتراح التصميم

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

التحكّم في إمكانية العرض:

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

API

ستتم إضافة ما يلي إلى مكتبة privacysandbox.ui.core:

• SessionObserver: يتم تنفيذ هذا الإجراء عادةً من خلال حزمة تطوير البرامج (SDK) للقياس، المرفقة بالجلسة التي تعرضها حزمة SDK من خلال privacysandbox.ui. كما ستتيح هذه الواجهة لحزمة تطوير البرامج للقياس إمكانية تفعيل فئات معينة من إشارات إمكانية العرض. ويؤدي هذا بدوره إلى تمكين مكتبة عملاء واجهة المستخدم من جمع الإشارات التي يهتم بها المراقب فقط، وهو أمر أفضل لسلامة النظام بشكل عام.
• registerObserver(): تمت إضافة هذه الطريقة إلى الصف Session، وهي تتيح لأي مستخدم لديه إذن الوصول إلى الجلسة أن يسجّل مراقبًا. إذا تمّ تسجيل المراقب بعد فتح جلسة واجهة المستخدم، سيتلقّى رمز النسخة المخزَّنة مؤقتًا AdContainerInfo على الفور. في حال التسجيل قبل فتح الجلسة، سيتم إرسالها بتاريخ AdContainerInfo عند فتحها.
• AdContainerInfo: فئة تحتوي على علامات حروف تُتيح للمراقب الحصول على معلومات عن حاوية الإعلان للقراءة فقط لأنواع البيانات الواردة في قسم الصفات أعلاه. تتجاوب قيم النتيجة من هذه القيم، كلما أمكن، مع القيم المعروضة القابلة للدمج من القيم المتوفرة حاليًا في View وفئاتها الفرعية. إذا تم إنشاء حاوية الإعلان باستخدام Jetpack Compose، سيؤدّي ذلك إلى عرض الخصائص الدلالية للحاويات. يمكن استخدام هذه الفئة لحساب أحداث MRAID وOMID ذات الصلة بإمكانية العرض.
• SessionObserverotifyAdContainerChanged(): تُستخدَم لإعلام المراقب عندما تتغيّر إمكانية العرض. تمرِّر كائن AdContainerInfo. ويسمى ذلك عند رصد أحداث تؤثر في أنواع البيانات المدرَجة في قسم "الإمكانات". ملاحظة: يمكن استدعاء هذه الطريقة بالإضافة إلى الطرق في "الجلسة". على سبيل المثال، يتم استدعاء Session.notifyResized() لطلب تغيير حجم الإعلان من حزمة تطوير البرامج (SDK)، ويتم استدعاء SessionObserver.notifyAdContainerChanged() أيضًا عند حدوث ذلك.
• SessionObserverotifySessionClosed(): يُعلم المراقب بأن الجلسة قد تم إغلاقها.

ملاحظة: ترتبط مدة SessionObserver منذ الجلسة بمدة الجلسة. إذا تم إغلاق الجلسة، سيستلم SessionObserver مكالمة notifySessionClosed()، ولن يتم إرسال أي طرق أخرى إليه. وبما أنّه يمكن إغلاق الجلسة من خلال حزمة تطوير البرامج (SDK) لمزوِّد واجهة المستخدم، أو عند فصل SandboxedSdkView عن نافذة تطبيق الناشر، من المهم أن تميّز حزمة تطوير البرامج (SDK) للقياس بين جلسة واجهة المستخدم وجلسة الإعلان. وقد تكون هناك جلسات متعددة يتم عرض الإعلان لها على سبيل المثال، إذا لم يعالج الناشر عمليات تدوير الأجهزة، ستتم إعادة تشغيل نشاطه كلما تم تدوير الجهاز. عند حذف النشاط، سيتم فصل SandboxedSdkView عن النافذة وإغلاق جلسة واجهة المستخدم. إذا حفظ الناشر محوّل واجهة المستخدم خلال إعادة تشغيل النشاط، قد يتمكن من إرفاق المحوّل نفسه بـ SandboxedSdkView جديد، وفتح جلسة جديدة بعد بدء النشاط. سيحصل شريك القياس على إرفاق مراقب بالجلسة الجديدة، وقد يختار إعادة استخدام المراقِب المرفق بجلسة سابقة لمواصلة القياس.

التحسينات المستقبلية

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

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

الأسئلة المفتوحة

نحن نرحّب بملاحظاتك بشأن النقاط التالية:

1. ما هي إشارات إمكانية العرض التي تهتم بها وغير مذكورة في هذا الشرح؟
2. الاقتراح الحالي هو تعديل إمكانية العرض بمعدّل لا يقلّ عن كل 200 ملّي ثانية، بشرط حدوث تغيير ذي صلة في واجهة المستخدم. هل هذا التكرار مقبول بالنسبة لك؟ إذا لم يكن كذلك، ما معدل التكرار الذي تفضله؟
3. هل تفضِّل تحليل المعلومات من setTrustedPresentationCallback بنفسك، أو السماح لمكتبة واجهة المستخدم الخاصة بالموفِّر بحذف البيانات من مكتبة واجهة واجهة المستخدم الخاصة بالعميل، عندما لا تكون البيانات مطابقة لبيانات setTrustedPresentationCallback؟
4. كيف تستهلك إشارات إمكانية العرض؟ يُرجى مساعدتنا في فهم حالات استخدامك من خلال تقديم ملاحظات تجيب على هذه الأسئلة.