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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يسمح "وقت تشغيل حِزم 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 استخدامها لعرض واجهة المستخدم في جميع العمليات، وإبقاءها محدّثة أثناء تفاعل المستخدم معها ومع الجهاز.

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

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

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

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

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

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

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

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

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

التحكّم في التدفق

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

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

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

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

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

ترتيب Z

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

عندما يكون 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 مؤقتًا على false لوضع واجهة مستخدم الإعلان أسفل نافذة الناشر. بعد إغلاق القائمة المنسدلة، اتصل على الرقم التالي: orderProviderUiAboveClientUi إلى true.

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

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

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

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