SDK Runtime محدودیتهایی را در مورد نحوه راهاندازی فعالیتهای جدید توسط SDK اعمال میکند. این یک چالش برای قالبهای تبلیغات تمام صفحه است که معمولاً به شروع یک فعالیت جداگانه برای کنترل پیشرفته و تجربه کاربر متکی هستند. برای پرداختن به این موضوع، SDK Runtime مکانیزم جدیدی را برای فعالیتهای sandbox معرفی میکند.
SDK های بارگیری شده در محیط SDK Runtime نمی توانند مستقیماً برچسب های <activity>
را در مانیفست خود تعریف کنند یا فعالیت های خود را آغاز کنند. در عوض، یک اقدام قصد جدید، START_SANDBOXED_ACTIVITY
، معرفی شده است.
در حالی که SDK ها نیز از راه اندازی intent با این عملکرد محدود می شوند، SDK ها می توانند از برنامه مشتری درخواست کنند که این هدف را آغاز کند. سپس سیستم یک فعالیت تعریف شده توسط پلتفرم ایجاد می کند و آن را به SDK ارسال می کند. این فعالیت در همان فرآیند SDK اجرا خواهد شد.
سپس SDK می تواند از این فعالیت برای پیاده سازی و مدیریت تجربه تبلیغات تمام صفحه استفاده کند.
فعالیت ارائه شده توسط پلت فرم یک android.app.Activity
استاندارد است که به عنوان بخشی از وظیفه برنامه مشتری راه اندازی شده است.
ایجاد فعالیت در 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 برای درخواست از برنامه برای راه اندازی فعالیت ها استفاده می شود.
جریان راه اندازی فعالیت ها با کتابخانه های فعالیت به شرح زیر است:
- SDK پارامتری از نوع
SdkActivityLauncher
را به هر API که شروع به فعالیت می کند اضافه می کند. - برنامه مشتری در یکی از فعالیتهای خود
createSdkActivityLauncher
را فراخوانی میکند تا راهاندازی ایجاد کند که میتواند در تماسهای API به SDK ارسال شود. - SDK
SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat)
را فراخوانی می کند و توکن شناسه را بازیابی می کند. - SDK برای راه اندازی فعالیت،
launchSdkActivity
فراخوانی می کند.
نمودار زیر جریان را در صورت استفاده از کتابخانه های فعالیت نشان می دهد.
![نمودار توالی کتابخانه فعالیت](https://developers.google.cn/static/privacy-sandbox/private-advertising/sdk-runtime/full-screen-ads/ActivityLibrarySequence.png?hl=fa)
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 ها باید این جریان را دنبال کنند:
- SDK با استفاده از API های ارائه شده، یک کنترل کننده فعالیت را ثبت می کند و یک شناسه به دست می آورد.
- SDK این شناسه را با برنامه مشتری خود به اشتراک می گذارد.
- برنامه سرویس گیرنده روشی را برای شروع یک فعالیت در زمان اجرا SDK با پلتفرم API
startSdkSandboxActivity(Activity, IBinder)
فراخوانی می کند، و به عنوان پارامتر، فعالیت شروع انتخاب شده برای این فعالیت جدید و شناسه Activity Handler را ارسال می کند. - پلتفرم یک Activity را شروع میکند و از طریق یک فراخوان در Activity Handler به SDK اطلاع میدهد (
SdkSandboxActivityHandler.onActivityCreated(Activity)
). - SDK از فعالیت برای پر کردن آن با آگهی استفاده می کند.
استفاده از APIهای پلتفرم، SDK را مسئول میکند که شناسه SdkSandboxActivityHandler را از طریق APIهایش در زمان مناسب با برنامه مشتری به اشتراک بگذارد و برنامههای سرویس گیرنده را در مورد نحوه استفاده از آن راهنمایی کند.
در نمودار جریان زیر، نمونه SDK دارای یک متد launchActivity(AppCallback)
است که انتظار یک تماس را دارد (به عنوان بخشی از API SDK تعریف شده است). این پاسخ تماس توسط SDK برای اشتراکگذاری شناسه Activity Handler ( SdkSandboxActivityHandler
) با برنامه مشتری استفاده میشود.
![نمودار توالی API های پلتفرم](https://developers.google.cn/static/privacy-sandbox/private-advertising/sdk-runtime/full-screen-ads/platformAPIssequence.png?hl=fa)
قابلیت مشاهده
در 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
برای مدیریت پیمایش برگشتی استفاده شود.