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

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

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

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

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

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

إنشاء نشاط في "وقت تشغيل حزمة تطوير البرامج (SDK)"

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

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

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

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

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

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

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

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

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

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

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

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

مخطّط تسلسلي لمكتبة الأنشطة
مخطّط تسلسلي يوضّح تدفّق بدء نشاط باستخدام مكتبات الأنشطة

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

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

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

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

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

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

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

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

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

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

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

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

مراحل النشاط

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

الرجوع إلى الصفحة السابقة

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