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

يتيح "وقت تشغيل SDK" تشغيل حِزم SDK لعرض الإعلانات في بيئة وضع حماية، ما يمنعها من الوصول إلى العرض الهرمي للناشر. لعرض الإعلانات، تعرض المنصة واجهة برمجة تطبيقات SandboxedSdkProvider.getView لحزمة تطوير البرامج (SDK) للحصول على مشاهدة للإعلان، وتعبئتها في شكل SurfacePackage لإرسالها من خلال IPC (الاتصال بين العمليات) إلى تطبيق العميل. لهذا السبب، هناك العديد من العيوب، والتي تمت مناقشتها أدناه. سيقدم هذا المستند بعد ذلك مكتبة 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:

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

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

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

SessionClient: التي أنشأتها مكتبة البرامج، وهو يشكِّل نهاية نفق الاتصال بين حزمة تطوير البرامج (SDK) والناشر.

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

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

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

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

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

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

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

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

تغيير واجهة المستخدم من إجراء الناشر

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

الانتقال

عند ترتيب واجهة مستخدم الإعلان فوق نافذة الناشر، يتم إرسال 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.

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

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

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

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