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

تقديم ملاحظات

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

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

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

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

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

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

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

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

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

النشاط المكتبات توفر العديد من الإيجابيات:

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

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

  • توفر المكتبة الأساسية الواجهات التي تستخدمها تطبيقات العميل ومكتبات موفر الخدمة.
  • توفر مكتبة provider واجهات برمجة تطبيقات لحزم 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):

  • SdkSandboxActivityHandler: يتم استخدام "معالج النشاط" لإشعار حزمة تطوير البرامج (SDK) عند إنشاء نشاط، ويتم تسجيله من خلال حزمة SDK.
  • للمساعدة في تسجيل "معالجات النشاط"، يمكن لحزمة تطوير البرامج (SDK) استخدام الطرق التالية ضمن SdkSandboxController:
  • SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): يتم استدعاء هذه الطريقة من تطبيق العميل، وتؤدي هذه الطريقة إلى إنشاء أنشطة لحزمة تطوير البرامج (SDK). يجب أن يتم تمرير تطبيق العميل كمَعلمات لنشاط البدء الذي تم اختياره ومعرّف معالج النشاط في حزمة تطوير البرامج (SDK).

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

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

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

وفي مخطط التدفق التالي، يتضمن مثال SDK طريقة launchActivity(AppCallback) التي تتوقع حدوث (يتم تعريفها كجزء من واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK)). يتم استخدام معاودة الاتصال هذه من قِبل حزمة تطوير البرامج (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 الحالات للتعامل مع التنقل الخلفي.