واجهات برمجة التطبيقات للعروض التقديمية لواجهة المستخدم في وقت تشغيل حزمة تطوير البرامج (SDK)

يسمح "وقت تشغيل حزمة تطوير البرامج (SDK)" بتشغيل حِزم SDK لعرض الإعلانات في بيئة محمية بوضع الحماية، ما يمنعها من الوصول إلى التسلسل الهرمي لمشاهدات الناشر. لعرض الإعلانات، يجب أن تتضمن السمة تعرض المنصة واجهة برمجة تطبيقات SandboxedSdkProvider.getView لحزمة تطوير البرامج (SDK) من أجل الحصول على إعلان وتحمله كـ SurfacePackage لإرساله عبر IPC (الاتصال بين العمليات) إلى تطبيق العميل. يحتوي هذا على العديد وعيوب، والتي ستتم مناقشتها أدناه. سيقدّم هذا المستند بعد ذلك مكتبة ‎proposed Jetpack التي يتم إنشاؤها لمواجهة هذه التحديات.

الأسباب المنطقية لإضافة واجهات برمجة تطبيقات النظام الأساسي

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

  1. السماح لحزمة SDK بإدارة مرّات ظهور الإعلانات المتعدّدة خلال فترة عرضها ومعرفة ما يحدث لواجهة مستخدم الإعلان بعد أن تنشئها حزمة SDK
  2. فصل عملية إنشاء العرض عن عملية ربط المحتوى يتيح استخدام القناة الجانبية حزمة SDK لعرض كائن يتوافق مع طلب الإعلان إلى التطبيق (المحتوى)، والذي يمكن ربطه بحاوية الإعلان عندما يرى التطبيق مناسبًا.
  3. تزيل العناصر الأساسية للنظام الأساسي المستخدَمة لعرض واجهة المستخدم في العمليات. (تستخدم المنصة حاليًا SurfaceControlViewhost إلى إنشاء SurfacePackage منه).
  4. تفعِّل حِزم SDK لعرض الإعلانات في وقت تشغيل حزمة SDK تلقائيًا تلقّي الإشعارات عند تغيير واجهة مستخدم حاوية الإعلان. إذا غيّر الناشر تنسيق حاوية الإعلان، لن تدرك حزمة تطوير البرامج (SDK) هذه التغييرات ما لم يطلب الناشر واجهة برمجة تطبيقات صراحةً لإعلامها بذلك.
  5. مزامنة تغييرات تغيير واجهة مستخدم الإعلان وحاوية الإعلان بدون أي بيانات غير مرغوب فيها مرئية للمستخدم
  6. إدارة التوافق مع الإصدارات السابقة تلقائيًا لا يتوفر SurfacePackage قبل المستوى 30 لواجهة برمجة التطبيقات. بالإضافة إلى ذلك، على الأجهزة التي لا تتوفّر فيها مدة تنفيذ حزمة SDK وتكون حزمة SDK محلية للناشر، من غير المجدي إنشاء SurfacePackage لإعلان عندما يمكن الحصول على مرّة ظهور مباشرةً من حزمة SDK. وتزيل القناة الجانبية هذه التعقيدات من حزمة SDK ورمز المطوّر للتطبيق.
  7. تفعيل واجهة مستخدم الإعلان للدمج بسلاسة مع العناصر القابلة للتعديل. يمكن أيضًا لمطوّري Jetpack Compose الذين لا يعملون مع المشاهد مواصلة استضافة واجهة المستخدم التي أنشأها مطوّر حزمة SDK الذي لا يزال يعمل مع المشاهد.

مكتبات واجهة المستخدم

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

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

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

في ما يلي واجهات برمجة التطبيقات للعرض التقديمي لواجهة مستخدم وقت تشغيل حزمة تطوير البرامج (SDK):

SandboxedUiAdapter: تم إنشاؤه بواسطة حزمة تطوير البرامج (SDK)، مما يوفر طريقة للحصول على المحتوى ليتم عرضه في واجهة مستخدم الناشر

‫SandboxedSdkView: حاوية أنشأها الناشر تحتوي على محتوى تم الحصول عليه من خلال SandboxedUiAdapter.

‫Session: تم إنشاؤه بواسطة حزمة SDK استجابةً لحالة العميل SandboxedUiAdapter.openSession(). يمثّل جلسة واحدة من واجهة المستخدم. ويشكّل ذلك طرف حزمة SDK من نفق الاتّصال بين حزمة SDK والناشر، ويتلقّى إشعارات بشأن التغييرات في SandboxedSdkView، مثل إزالة النوافذ أو تغيير حجمها أو تغييرات الإعدادات.

‫SessionClient: تم إنشاؤه من قِبل مكتبة العميل، ويشكّل هذا العنصر الطرف الذي يمثّل الناشر لنفق الاتصال بين حزمة SDK والناشر.

SandboxedSdkUiSessionStateChangedListener: تم إنشاؤها من قِبل الناشر. حاسمة أداة معالجة التغييرات التي تطرأ على حالة جلسة واجهة المستخدم المرتبطة SandboxedSdkView

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

اطّلِع على المستندات المرجعية لـ privacysandbox-ui للحصول على مزيد من التفاصيل حول واجهات برمجة التطبيقات هذه.

مسار التحكّم

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

يوضّح المخطّط السابق كيف يمكن للناشر إنشاء SandboxedSdkView. آليًا أو من خلال ملف XML وإرفاقه بـ SdkSandboxUiAdapter يتم الحصول عليها من حزمة SDK من خلال واجهة برمجة تطبيقات معرّفة بحزمة SDK. لرصد جميع التغيُّرات في حالة واجهة المستخدم، يجب أن يضيف الناشر SandboxedSdkUiSessionStateChangedListener إلى SandboxedSdkView قبل إرفاق SdkSandboxUiAdapter.

صورة توضيحية تعرِض عملية فتح الجلسة
الحصول على واجهة المستخدم من حزمة تطوير البرامج (SDK)

يوضّح هذا المخطّط البياني كيف إذا كان نشاط الناشر يتعامل مع تغييرات الضبط فإن مكتبة العملاء تتولى إعادة توجيه تغيير التهيئة إلى SDK، حتى يتمكنوا من تحديث واجهة المستخدم الخاصة بهم وفقًا لذلك. على سبيل المثال، يمكن بدء هذا المسار عندما يدير المستخدم الجهاز ويعلن الناشر عن معالجة تغييرات الإعدادات في نشاطه، من خلال ضبط android:configChanges=["orientation"].

التغيير الذي يبدأه الناشر في واجهة المستخدم

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

تغيير واجهة المستخدم الذي يبدأ من حزمة SDK

يوضّح هذا المخطّط البياني كيفية إغلاق الجلسة عند فصل SandboxedSdkView. من النافذة. يمكن أيضًا إغلاق الجلسة في أي وقت (مثلاً عندما يفقد المستخدم اتصاله بالشبكة) من خلال حزمة SDK من خلال استدعاء SessionClient.onSessionError().

يتم إغلاق جلسة واجهة المستخدم.

ترتيب Z

تستخدم مكتبة واجهة المستخدم للعملاء SurfaceView داخليًا لاستضافة واجهة مستخدم حزمة SDK. يمكن أن يستخدم SurfaceView ترتيب Z لعرض واجهة المستخدم أعلى الناشر أو تحته. يتم التحكم في هذا من خلال SandboxedSdkView.orderProviderUiAboveClientUi()، التي تقبل القيمة المنطقية setOnTop.

عندما تكون قيمة الحقل "setOnTop" هي true، كل android.view.MotionEvent في تم إرسال SandboxedSdkView إلى حزمة تطوير البرامج (SDK). عندما false، يتم إرسال هذه الرسائل إلى الناشر. يتم تلقائيًا إرسال أحداث الحركة إلى حزمة تطوير البرامج (SDK).

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

الانتقال

عندما يتم ترتيب واجهة مستخدم الإعلان على محور Z أعلى نافذة الناشر، يتم إرسال MotionEvents من واجهة مستخدم الإعلان إلى حزمة SDK. تتلقّى إيماءات التمرير السريع والرمي التي يتم بدءها على واجهة مستخدِم الإعلان معاملة خاصة:

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

دليل التنفيذ

يجب أن تنفِّذ حزمة SDK ما يلي:

  • SandboxedUiAdapter: يتم إرجاع هذا الحقل إلى الناشر ردًا على واجهة برمجة التطبيقات التي تم تحديدها بحزمة SDK، مثل loadAd. الطريقة openSession() لهذه الطريقة تنفيذ طلب الإعلان إلى خوادم حزمة تطوير البرامج (SDK) إعداد طريقة عرض إعلان لهذا الطلب.
  • Session**: يتم عرض هذا الردّ استجابةً للمكالمة التي أجريتها بتاريخ SandboxedUiAdapter.openSession. وتوفّر هذه الواجهة طريقة لحصول مكتبة العميل على واجهة مستخدم الإعلان وإرسال إشعار إلى حزمة تطوير البرامج (SDK) بشأن التغييرات في واجهة برمجة التطبيقات هذه. الكل يجب تنفيذ Session طريقة هنا.

على الناشر إجراء ما يلي:

  1. يمكنك إنشاء SandboxedSdkView، إما من خلال ملف XML أو آليًا.
  2. يمكنك إرفاق SandboxedSdkUiSessionStateChangedListener بالملف SandboxedSdkView لمراقبة التغييرات في واجهة المستخدم.
  3. إرفاق حزمة تطوير برامج (SDK) يوفّرها SandboxedUiAdapter بالملف SandboxedSdkView
  4. إضافة SandboxedSdkView إلى النافذة كالمعتاد والسماح لمكتبة البرامج عليك الحرص على إنشاء جلسة واجهة المستخدم وصيانتها باستخدام حزمة SDK.
  5. في الأوقات المناسبة، يمكنك التفاعل مع التغييرات في الحالة التي أبلغ عنها SandboxedSdkUiSessionChangedListener. على سبيل المثال، إذا أغلقت حزمة SDK بشكل غير متوقع، يمكن للناشر استبدال SandboxedSdkView بـ صورة ثابتة، أو إزالتها من العرض الهرمي.
  6. عند إجراء انتقالات قد تشمل واجهة مستخدم الإعلان، مثل القائمة المنسدلة، orderProviderUiAboveClientUi مؤقتًا إلى خطأ لتحديد موضع واجهة مستخدم الإعلان أسفل نافذة الناشر. وبمجرد إغلاق القائمة المنسدلة، اتصل orderProviderUiAboveClientUi إلى true

مستقبل واجهات برمجة تطبيقات المنصة

بعد طرح مكتبات واجهة المستخدم في إصدار تجريبي، نخطّط لإيقاف نهائيًا واجهات برمجة تطبيقات وقت تشغيل حزمة تطوير البرامج لنظام التشغيل ذات الصلة بعرض واجهة المستخدم، وهي SdkSandboxManager.requestSurfacePackage() وSandbxedSdkProvider.getView().

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

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