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

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

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

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

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

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

تنبيه: يتوافق النشاط المقدَّم (android.app.Activity) بشكل محدود مع بعض مكتبات AndroidX من جانب حزمة تطوير البرامج (SDK)، لا سيما أداة Compose.

تنبيه: يجب عدم استخدام Context من هذا النشاط مباشرةً في حزمة SDK. بدلاً من ذلك، يجب أن تستخدم حِزم SDK SandboxedSdkProvider#getContext() للحصول على السياق المناسب لعملياتها.

إنشاء الأنشطة في "وقت تشغيل حزمة تطوير البرامج (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 لإنشاء أنشطة، يمكنه تمرير تعبير فلتر عند إنشاء مشغّل التطبيقات. إذا كان التطبيق لا يريد إنشاء نشاط كشرط، يمكنه جعل القيمة التي تشير إلى عمود القيمة true دائمًا.

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

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

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

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

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

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

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

ملاحظة: يتم استدعاء onActivityCreated(Activity) من خلال Activity.onCreate(Bundle)، يُتوقّع من هذه المرحلة تعبئة حِزم تطوير البرامج (SDK) لعرض المحتوى.

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

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

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

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

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

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

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

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

دورة الحياة

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

التنقّل الخلفي

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