پشتیبانی از فعالیت برای تبلیغات تمام صفحه

SDK Runtime محدودیت‌هایی را در مورد نحوه‌ی راه‌اندازی فعالیت‌های جدید توسط SDKها اعمال می‌کند. این موضوع، چالشی را برای قالب‌های تبلیغاتی تمام‌صفحه ایجاد می‌کند که معمولاً برای کنترل و تجربه‌ی کاربری بهتر، به شروع یک فعالیت جداگانه متکی هستند. برای حل این مشکل، SDK Runtime مکانیسم جدیدی را برای فعالیت‌های sandboxed معرفی می‌کند.

SDK های بارگذاری شده در محیط زمان اجرای SDK نمی‌توانند مستقیماً تگ‌های <activity> را در مانیفست خود تعریف کنند یا فعالیت‌های خود را آغاز کنند. در عوض، یک اقدام intent جدید، START_SANDBOXED_ACTIVITY ، معرفی شده است.

اگرچه SDKها نیز از اجرای اینتنت‌ها با این اقدام منع شده‌اند، SDKها می‌توانند از برنامه‌ی کلاینت درخواست کنند که این اینتنت را آغاز کند. سپس سیستم یک اکتیویتی تعریف‌شده توسط پلتفرم ایجاد می‌کند و آن را به SDK ارسال می‌کند. این اکتیویتی در همان فرآیند SDK اجرا خواهد شد.

سپس SDK می‌تواند از این فعالیت برای پیاده‌سازی و مدیریت تجربه تبلیغات تمام صفحه استفاده کند.

فعالیتی که توسط پلتفرم ارائه می‌شود، یک android.app.Activity استاندارد است که به عنوان بخشی از وظیفه برنامه کلاینت راه‌اندازی می‌شود.

ایجاد اکتیویتی در SDK Runtime

شما دو روش اصلی برای ایجاد فعالیت‌ها دارید: استفاده از کتابخانه‌های ساده‌شده‌ی Jetpack Activity یا تعامل مستقیم با APIهای پلتفرم .

ما استفاده از کتابخانه‌های Activity را توصیه می‌کنیم زیرا آنها با انتزاع پیچیدگی‌های اساسی، ایجاد activity را ساده می‌کنند.

کتابخانه‌های فعالیت

کتابخانه‌های فعالیت چندین مزیت ارائه می‌دهند:

• جزئیات داخلی ثبت کنترل‌کننده‌های فعالیت و اشتراک‌گذاری شناسه‌های آنها با برنامه‌های کلاینت را خلاصه کنید.
• به توسعه‌دهندگان برنامه، با اجازه دادن به آنها برای تعیین شرایط (گزاره‌ها) برای برآورده شدن، کنترل بیشتری بر نحوه ایجاد فعالیت‌ها در برنامه‌هایشان توسط SDKها می‌دهد.
• یک روش یکپارچه برای SDKها ایجاد کنید تا APIهایی را که فعالیت‌ها را راه‌اندازی می‌کنند، تعریف کنند.

سه کتابخانه فعالیت وجود دارد: هسته، کلاینت و ارائه دهنده.

• کتابخانه اصلی رابط‌های مورد استفاده توسط برنامه‌های کلاینت و کتابخانه‌های ارائه‌دهنده را فراهم می‌کند.
• کتابخانه ارائه دهنده، APIهایی را برای SDKها فراهم می‌کند تا فعالیت‌ها را راه‌اندازی کنند.
• کتابخانه کلاینت، APIهایی را برای برنامه‌های کلاینت فراهم می‌کند تا یک لانچر فعالیت ایجاد کنند، که SDKها می‌توانند از آن برای درخواست برنامه‌ها برای راه‌اندازی فعالیت‌ها استفاده کنند.

این کتابخانه‌ها APIهای زیر را معرفی می‌کنند:

• SdkActivityLauncher : لانچر فعالیت به SDKها اجازه می‌دهد تا فعالیت‌های راه‌اندازی را از برنامه کلاینت مدیریت کنند. برنامه‌های کلاینت باید یک لانچر ایجاد کنند و آن را به عنوان پارامتر به APIهای SDK که فعالیت‌ها را شروع می‌کنند، ارسال کنند.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ) : یک تابع افزونه که برنامه کلاینت می‌تواند از activity های خود برای ایجاد launcher ها فراخوانی کند.
• SdkActivityLauncher.launchSdkActivity(IBinder) : روشی که توسط SDK برای درخواست اجرای اکتیویتی‌ها توسط برنامه استفاده می‌شود.

جریان راه‌اندازی فعالیت‌ها با کتابخانه‌های فعالیت به شرح زیر است:

1. SDK پارامتری از نوع SdkActivityLauncher را به هر API که فعالیت‌ها را شروع می‌کند، اضافه می‌کند.
2. برنامه‌ی کلاینت، createSdkActivityLauncher را در یکی از اکتیویتی‌های خود فراخوانی می‌کند تا یک لانچر ایجاد کند که بتواند در فراخوانی‌های API به SDK ارسال شود.
3. SDK، تابع SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) را فراخوانی کرده و توکن شناسه را بازیابی می‌کند.
4. SDK، launchSdkActivity را برای راه‌اندازی اکتیویتی فراخوانی می‌کند.

نمودار زیر جریان کار را در صورت استفاده از کتابخانه‌های فعالیت نشان می‌دهد.

APIهای پلتفرم

این پلتفرم APIهای زیر را برای تسهیل ایجاد و مدیریت فعالیت‌های سندباکس‌شده در SDK Runtime معرفی می‌کند:

• SdkSandboxActivityHandler : از Activity Handler برای اطلاع‌رسانی به SDK هنگام ایجاد یک Activity استفاده می‌شود و توسط SDK ثبت می‌شود.
• برای کمک به ثبت Activity Handlers، SDK می‌تواند از متدهای زیر در SdkSandboxController استفاده کند:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler) : یک نمونه از SdkSandboxActivityHandler ثبت می‌کند که یک شناسه IBinder برمی‌گرداند.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler) : یک نمونه ثبت‌شده از SdkSandboxActivityHandler را با استفاده از شناسه‌اش لغو ثبت می‌کند.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder) : این متد که از برنامه‌ی کلاینت فراخوانی می‌شود، ایجاد فعالیت‌ها برای SDK را آغاز می‌کند. برنامه‌ی کلاینت باید فعالیت آغازین انتخابی خود و شناسه‌ی Activity Handler مربوط به SDK را به عنوان پارامتر ارسال کند.

برای شروع یک فعالیت با استفاده از APIهای پلتفرم، SDKها باید از این جریان پیروی کنند:

1. SDK با استفاده از APIهای ارائه شده، یک activity handler ثبت می‌کند و یک شناسه دریافت می‌کند.
2. SDK این شناسه را با برنامه کلاینت خود به اشتراک می‌گذارد.
3. برنامه‌ی کلاینت، متدی را برای شروع یک فعالیت در SDK Runtime با API پلتفرم startSdkSandboxActivity(Activity, IBinder) فراخوانی می‌کند و فعالیت شروع انتخاب شده برای این فعالیت جدید و شناسه‌ی Activity Handler را به عنوان پارامترها ارسال می‌کند.
4. پلتفرم یک Activity را شروع می‌کند و از طریق یک فراخوانی در Activity Handler ( SdkSandboxActivityHandler.onActivityCreated(Activity) ) به SDK اطلاع می‌دهد.
5. SDK از این فعالیت برای پر کردن آن با یک تبلیغ استفاده می‌کند.

استفاده از APIهای پلتفرم، SDK را مسئول می‌کند تا شناسه SdkSandboxActivityHandler را از طریق APIهای خود در زمان مناسب با برنامه کلاینت به اشتراک بگذارد و برنامه‌های کلاینت را در مورد نحوه استفاده از آن راهنمایی کند.

در نمودار جریان زیر، SDK نمونه دارای متدی به نام launchActivity(AppCallback) است که انتظار یک فراخوانی (callback) را دارد (که به عنوان بخشی از API SDK تعریف شده است). این فراخوانی توسط SDK برای به اشتراک گذاشتن شناسه Activity Handler ( SdkSandboxActivityHandler ) با برنامه کلاینت استفاده می‌شود.

قابلیت مشاهده

در SDK Runtime، تبلیغاتی که در سلسله مراتب نمای برنامه کلاینت ادغام شده‌اند، از کانال‌های جانبی برای رندر نماهای SDK از فرآیند SDK به فرآیند برنامه کلاینت استفاده می‌کنند.

SDK نمی‌تواند از همان APIهای View که در خارج از زمان اجرای SDK برای تعیین قابل مشاهده بودن تبلیغ برای کاربر استفاده می‌کنند، استفاده کند، زیرا نمای تبلیغ به پنجره برنامه ( Viewability ) متصل نیست.

در مقابل، فعالیت ارائه شده توسط پلتفرم به صورت بومی در فرآیند SDK Runtime اجرا می‌شود و نیاز به کانال‌های جانبی را از بین می‌برد و به SDKها اجازه می‌دهد تا از APIهای استاندارد Android Activity و View استفاده کنند.

با توجه به این پیاده‌سازی‌های مختلف، تلاش‌های مداوم با هدف یکپارچه‌سازی رابط‌ها برای بازیابی سیگنال‌های قابلیت مشاهده صرف نظر از زمینه بارگذاری تبلیغ انجام می‌شود.

چرخه حیات

ActivityHolder از طریق SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) به SDK منتقل می‌شود و LifecycleOwner پیاده‌سازی می‌کند و می‌توان از آن برای اطلاع از Lifecycle.Event استفاده کرد.

ناوبری برگشت

متد ActivityHolder.getOnBackPressedDispatcher() مقدار OnBackPressedDispatcher را برمی‌گرداند که می‌تواند برای ثبت نمونه‌های OnBackPressedCallback جهت مدیریت پیمایش برگشتی استفاده شود.