دعم النشاط للإعلانات بملء الشاشة

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

لا يمكن لحِزم SDK المحمَّلة ضمن بيئة "وقت تشغيل حِزم SDK" تحديد علامات <activity> مباشرةً في ملف البيان الخاص بها أو بدء أنشطتها الخاصة. بدلاً من ذلك، تمّ تقديم إجراء نية جديد، وهو START_SANDBOXED_ACTIVITY.

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

يمكن لحزمة SDK بعد ذلك استخدام هذا النشاط لتنفيذ تجربة الإعلانات المعروضة بملء الشاشة وإدارتها.

النشاط الذي تقدّمه المنصة هو android.app.Activity عادي، يتم تشغيله كجزء من مهمة تطبيق العميل.

إنشاء نشاط في وقت تشغيل حزمة SDK

تتوفّر لك طريقتان أساسيتان لإنشاء الأنشطة: استخدام مكتبات الأنشطة المبسّطة في Jetpack أو التفاعل مباشرةً مع واجهات برمجة تطبيقات المنصة.

ننصحك باستخدام مكتبات الأنشطة لأنّها تبسّط عملية إنشاء الأنشطة من خلال تبسيط التعقيد الأساسي.

مكتبات الأنشطة

توفّر مكتبات الأنشطة عدة مزايا:

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

هناك ثلاث مكتبات أنشطة: الأساسية والعميل والمزوّد.

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

تقدّم هذه المكتبات واجهات برمجة التطبيقات التالية:

  • SdkActivityLauncher: يسمح مشغّل الأنشطة لحِزم تطوير البرامج (SDK) بمعالجة بدء الأنشطة من تطبيق العميل. يجب أن تنشئ تطبيقات العميل مشغّلاً وتُمرره كمَعلمة إلى واجهات برمجة تطبيقات حِزم SDK التي تبدأ الأنشطة.
  • ‫<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): دالة إضافة يمكن لتطبيق العميل استدعاؤها من أنشطته لإنشاء مشغّلات.
  • ‫SdkActivityLauncher.launchSdkActivity(IBinder): طريقة تستخدمها حزمة تطوير البرامج (SDK) لطلب تشغيل الأنشطة من التطبيق.

في ما يلي خطوات بدء الأنشطة باستخدام مكتبات الأنشطة:

  1. تُضيف حزمة تطوير البرامج (SDK) مَعلمة من النوع SdkActivityLauncher إلى أي واجهات برمجة تطبيقات ستبدأ الأنشطة.
  2. يُطلِق تطبيق العميل createSdkActivityLauncher في أحد أنشطته لإنشاء مشغِّل يمكن تمريره إلى حزمة SDK عند إجراء طلبات البيانات من واجهة برمجة التطبيقات.
  3. تستدعي حزمة تطوير البرامج (SDK) SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) وتسترجع الرمز المميّز للمعرّف.
  4. تستدعي حزمة تطوير البرامج (SDK) دالة launchSdkActivity لبدء النشاط.

يوضّح الرسم البياني التالي عملية المعالجة في حال استخدام مكتبات الأنشطة.

مخطّط تسلسل مكتبة الأنشطة
مخطّط تسلسلي يعرض مسار بدء نشاط باستخدام مكتبات النشاط

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

تقدّم المنصة واجهات برمجة التطبيقات التالية لتسهيل إنشاء الأنشطة المُعلَّقة في مساحة معيّنة و إدارتها ضمن "وقت تشغيل حزمة SDK":

لبدء نشاط باستخدام واجهات برمجة تطبيقات Platform، يجب أن تتّبع حِزم تطوير البرامج (SDK) الخطوات التالية:

  1. تسجِّل حزمة SDK معالِج نشاط باستخدام واجهات برمجة التطبيقات المقدَّمة وتحصل على معرِّف.
  2. تشارك حزمة SDK هذا المعرّف مع تطبيق العميل.
  3. يستدعي تطبيق العميل طريقة بدء نشاط في وقت تشغيل حزمة تطوير البرامج (SDK) باستخدام واجهة برمجة التطبيقات للنظام الأساسي startSdkSandboxActivity(Activity, IBinder)، مع تمرير النشاط المُختار لبدء هذا النشاط الجديد كمَعلمات، ومعرّف "معالج النشاط".
  4. يبدأ النظام الأساسي نشاطًا ويُعلم حزمة SDK من خلال طلب استدعاء في "معالج النشاط" (SdkSandboxActivityHandler.onActivityCreated(Activity)).
  5. تستخدِم حزمة تطوير البرامج (SDK) النشاط لملئه بإعلان.

يؤدي استخدام واجهات برمجة تطبيقات النظام الأساسي إلى تحميل حزمة SDK مسؤولية مشاركة معرّف SdkSandboxActivityHandler مع تطبيق العميل من خلال واجهات برمجة التطبيقات في الوقت المناسب، وتوجيه تطبيقات العميل حول كيفية استخدامه.

في مخطّط التدفق البياني التالي، يحتوي مثال حزمة SDK على طريقة launchActivity(AppCallback) تتوقّع تلقي دالّة callback (يتم تحديدها كجزء من واجهة برمجة التطبيقات لحزمة SDK). تستخدِم حزمة SDK معالجة معاودة الاتصال هذه لمشاركة معرّف معالج النشاط (SdkSandboxActivityHandler) مع تطبيق العميل.

مخطّط تسلسل واجهات برمجة التطبيقات للنظام الأساسي
مخطّط تسلسلي يعرض مسار بدء نشاط باستخدام واجهات برمجة تطبيقات المنصة

إمكانية العرض

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

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

في المقابل، يتم تشغيل النشاط المقدَّم من النظام الأساسي بشكلٍ أصلي ضمن عملية "وقت تشغيل حزمة تطوير البرامج (SDK)"، ما يزيل الحاجة إلى القنوات الجانبية ويسمح لحِزم SDK باستخدام واجهات برمجة التطبيقات العادية لنظام التشغيل Android Activity وView.

ونظرًا لهذه عمليات التنفيذ المختلفة، تهدف الجهود الجارية إلى توحيد الواجهات لاسترداد إشارات مدى الرؤية بغض النظر عن سياق تحميل الإعلان.

دورة الحياة

إنّ القيمة ActivityHolder التي تم تمريرها إلى حزمة SDK من خلال SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) تنفِّذ LifecycleOwner ويمكن استخدامها للاطّلاع على Lifecycle.Event.

الانتقال إلى الصفحة السابقة

تُعرِض الطريقة ActivityHolder.getOnBackPressedDispatcher() OnBackPressedDispatcher التي يمكن استخدامها لتسجيل مثيلات OnBackPressedCallback لمعالجة التنقّل للخلف.