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

توجه: Privacy Sandbox در Android یک پروژه در حال انجام است و این سند طراحی فعلی آن را منعکس می کند. بازخورد شما ضروری است زیرا ما به توسعه و بهبود ویژگی های آن ادامه می دهیم.

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

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

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

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

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

احتیاط: فعالیت ارائه شده ( android.app.Activity ) با برخی از کتابخانه های AndroidX در سمت SDK، به ویژه Compose، پشتیبانی محدودی دارد.

احتیاط: Context این فعالیت نباید مستقیماً توسط SDK استفاده شود. در عوض، SDKها باید از SandboxedSdkProvider#getContext() برای بدست آوردن زمینه مناسب برای عملیات خود استفاده کنند.

ایجاد فعالیت در SDK Runtime

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

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

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

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

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

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

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

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

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

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

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

توجه: اگر برنامه سرویس گیرنده بخواهد شرطی برای SDKها برای ایجاد فعالیت‌ها اضافه کند، می‌تواند هنگام ایجاد راه‌انداز یک عبارت گزاره ارسال کند. اگر برنامه نمی‌خواهد ایجاد فعالیت را شرطی کند، می‌تواند بازگشت گزاره را همیشه true .

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

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

API های پلتفرم

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

• SdkSandboxActivityHandler : Activity Handler برای اطلاع رسانی به SDK هنگام ایجاد یک فعالیت استفاده می شود و توسط 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 های ارائه شده، یک کنترل کننده فعالیت را ثبت می کند و یک شناسه به دست می آورد.
2. SDK این شناسه را با برنامه مشتری خود به اشتراک می گذارد.
3. برنامه سرویس گیرنده روشی را برای شروع یک فعالیت در زمان اجرا SDK با پلتفرم API startSdkSandboxActivity(Activity, IBinder) فراخوانی می کند، و به عنوان پارامتر، فعالیت شروع انتخاب شده برای این فعالیت جدید و شناسه Activity Handler را ارسال می کند.
4. پلتفرم یک Activity را شروع می‌کند و از طریق یک فراخوان در Activity Handler به SDK اطلاع می‌دهد ( SdkSandboxActivityHandler.onActivityCreated(Activity) ).
5. SDK از فعالیت برای پر کردن آن با آگهی استفاده می کند.

توجه: onActivityCreated(Activity) از طریق Activity.onCreate(Bundle) فراخوانی می شود، انتظار می رود SDK ها نمای محتوا را در این مرحله پر کنند.

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

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

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

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

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

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

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

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

چرخه زندگی

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

ناوبری برگشتی

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