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

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

سبب إضافة ميزات إلى واجهات برمجة التطبيقات الخاصة بالمنصة

تم تصميم واجهات برمجة التطبيقات الخاصة بالإطار لتوفير المرونة، كما أنّ مهمة إنشاء قناة جانبية بين التطبيق وحزمة SDK لعرض واجهة المستخدم تقع على عاتق التطبيق وحزمة 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 استخدامها لعرض واجهة المستخدم على مستوى العمليات، وإبقائها محدَّثة أثناء تفاعل المستخدم معها ومع الجهاز.

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

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

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

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

SandboxedSdkView: هذا الحقل، الذي أنشأه الناشر، هو حاوية تتضمّن محتوًى تم الحصول عليه من خلال SandboxedUiAdapter.

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

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

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

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

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

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

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

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

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

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

ترتيب Z

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

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

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

الانتقال

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

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

دليل التنفيذ

يجب أن تنفّذ حزمة تطوير البرامج (SDK) ما يلي:

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

على الناشر اتّخاذ الإجراءات التالية:

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

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

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

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

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