SDK Runtime اجازه می دهد تا SDK های تبلیغاتی در یک محیط sandbox اجرا شوند و از دسترسی آنها به سلسله مراتب مشاهده ناشر جلوگیری می کند. برای نمایش تبلیغات، این پلتفرم یک SandboxedSdkProvider.getView
API را در اختیار SDK قرار می دهد تا یک نمای تبلیغاتی به دست آورد، و آن را به عنوان یک SurfacePackage
بسته بندی می کند تا از طریق IPC (ارتباط بین فرآیندی) به برنامه مشتری ارسال شود. این چند اشکال دارد که در ادامه به آنها پرداخته می شود. این سند سپس یک کتابخانه Jetpack پیشنهادی را ارائه می کند که برای رسیدگی به این چالش ها ساخته شده است.
دلیل تقویت APIهای پلتفرم
APIهای چارچوب برای انعطافپذیری طراحی شدهاند و وظیفه ایجاد یک کانال جانبی را برای ارائه UI تا برنامه و SDK واگذار میکنند. این کانال جانبی کارهای زیر را انجام می دهد:
- به SDK اجازه میدهد چندین بازدید از آگهی را در طول عمر خود مدیریت کند و بفهمد پس از ایجاد رابط کاربری تبلیغاتی توسط SDK چه اتفاقی میافتد.
- ایجاد و اتصال محتوا را جدا میکند. استفاده از کانال جانبی به SDK اجازه میدهد تا یک شی مطابق با درخواست آگهی را به برنامه (محتوا) برگرداند، که هر زمان که برنامه مناسب بداند میتواند به محفظه آگهی متصل شود.
- ساختارهای پلتفرم زیربنایی را که برای نشان دادن رابط کاربری در سراسر فرآیندها استفاده می شود، انتزاع می کند. (این پلتفرم در حال حاضر از
SurfaceControlViewhost
استفاده می کند و یکSurfacePackage
از آن تولید می کند.) - SDK های تبلیغات را در زمان اجرای SDK فعال می کند تا به صورت خودکار اعلان ها را هنگام تغییر رابط کاربری ظرف تبلیغات دریافت کنند. اگر ناشر طرحبندی ظرف تبلیغات را تغییر دهد، SDK از این تغییرات بیاطلاع میماند، مگر اینکه ناشر صریحاً با یک API تماس بگیرد تا به آن اطلاع دهد.
- تغییر اندازه رابط کاربری تبلیغات و ظرف تبلیغات را بدون هیچ گونه jank قابل مشاهده برای کاربر همگام می کند.
- سازگاری به عقب را به طور خودکار مدیریت می کند.
SurfacePackage
قبل از سطح API 30 در دسترس نیست. بهعلاوه، در دستگاههایی که زمان اجرای SDK وجود ندارد و SDK برای ناشر فرآیندی محلی است، ایجاد یکSurfacePackage
برای یک آگهی زمانی که میتوان نما را مستقیماً از SDK دریافت کرد، بیهوده است. کانال جانبی این پیچیدگی را از کد توسعهدهنده SDK و برنامه حذف میکند. - رابط کاربری تبلیغات را قادر می سازد تا به طور یکپارچه با Composables یکپارچه شود. توسعهدهندگان Jetpack Compose که با نماها کار نمیکنند نیز میتوانند به میزبانی رابط کاربری ایجاد شده توسط توسعهدهنده SDK که همچنان با نماها کار میکند، ادامه دهند.
کتابخانه های رابط کاربری
کتابخانههای UI پیچیدگیهای ذکر شده در بالا را انتزاعی میکنند و کانال جانبی را فراهم میکنند که ناشر و SDK میتوانند از آن برای نشان دادن رابط کاربری در سراسر فرآیندها استفاده کنند، و در هنگام تعامل کاربر با آن و با دستگاه، آن را بهروز نگه میدارند.
سه کتابخانه UI وجود دارد: هسته ، مشتری و ارائه دهنده . کتابخانه هسته رابط های مورد استفاده توسط کتابخانه های مشتری و ارائه دهنده را فراهم می کند. ارائهدهنده رابط کاربری (معمولاً SDK) به کتابخانه ارائهدهنده و مصرفکننده UI (معمولاً ناشر) به کتابخانه مشتری بستگی دارد. کتابخانه های مشتری و ارائه دهنده با هم کانال جانبی مورد نیاز برای ایجاد و نگهداری یک جلسه UI را تشکیل می دهند.
API ها
APIهای ارائه رابط کاربری SDK Runtime به شرح زیر است:
SandboxedUiAdapter
: ایجاد شده توسط SDK، که راهی برای به دست آوردن محتوا برای نمایش در UI ناشر ارائه می دهد.
SandboxedSdkView
: ایجاد شده توسط ناشر، این محفظه ای است که محتوای به دست آمده از طریق SandboxedUiAdapter
را در خود نگه می دارد.
Session
: توسط SDK در پاسخ به SandboxedUiAdapter.openSession()
ایجاد شده است. یک جلسه UI را نشان می دهد. تماس بگیرید. این انتهای SDK تونل ارتباطی بین SDK و ناشر را تشکیل میدهد و اعلانهایی درباره تغییرات SandboxedSdkView
، مانند جدا شدن پنجره، تغییر اندازه یا تغییرات پیکربندی دریافت میکند.
SessionClient
: ایجاد شده توسط کتابخانه مشتری، انتهای ناشر تونل ارتباطی بین SDK و ناشر را تشکیل می دهد.
SandboxedSdkUiSessionStateChangedListener
: ایجاد شده توسط ناشر. شنونده ای برای تغییرات در وضعیت جلسه رابط کاربری مرتبط با SandboxedSdkView
.
برای جزئیات بیشتر در مورد این APIها ، اسناد مرجع privacysandbox-ui را بخوانید.
جریان را کنترل کنید
نمودارهای زیر تعامل بین کتابخانه های UI مشتری و ارائه دهنده را در سناریوهای مختلف نشان می دهد:
نمودار قبلی نشان میدهد که چگونه ناشر میتواند یک SandboxedSdkView
به صورت برنامهنویسی یا از طریق XML خود ایجاد کند و آن را به SdkSandboxUiAdapter
که از SDK از طریق یک API تعریفشده توسط SDK به دست آمده است، متصل کند. برای مشاهده همه تغییرات حالت رابط کاربری، ناشر باید قبل از پیوست کردن SdkSandboxUiAdapter
SandboxedSdkUiSessionStateChangedListener
به SandboxedSdkView
اضافه کند.
این نمودار نشان میدهد که اگر فعالیت ناشر تغییرات پیکربندی را کنترل کند، کتابخانه سرویس گیرنده از ارسال تغییر پیکربندی به SDK مراقبت میکند، بنابراین آنها میتوانند رابط کاربری خود را بر این اساس بهروزرسانی کنند. به عنوان مثال، زمانی که کاربر دستگاه را بچرخاند و ناشر مدیریت تغییرات پیکربندی در فعالیت خود را با تنظیم android:configChanges=["orientation"]
اعلام کند، این جریان می تواند فعال شود.
این نمودار نشان میدهد که چگونه SDK میتواند با استفاده از روشهایی در SessionClient
درخواست تغییر در ظرف آگهی دهد. این API زمانی فعال میشود که SDK میخواهد اندازه آگهی را تغییر دهد و به ناشر نیاز دارد تا اندازه ظرف آگهی را برای سازگاری با ابعاد جدید تغییر دهد. این ممکن است در پاسخ به تعامل کاربر، مانند mraid.resize()
رخ دهد.
این نمودار نشان می دهد که چگونه وقتی SandboxedSdkView
از پنجره جدا می شود، جلسه بسته می شود. این جلسه همچنین می تواند در هر نقطه ای (مثلاً زمانی که کاربر اتصال به شبکه را از دست می دهد) توسط SDK با فراخوانی SessionClient.onSessionError()
بسته شود.
دستور Z
کتابخانه UI مشتری از SurfaceView
به صورت داخلی برای میزبانی رابط کاربری SDK استفاده می کند. SurfaceView
می تواند از دستور Z برای نشان دادن رابط کاربری خود در بالای پنجره ناشر یا زیر آن استفاده کند. این توسط روش SandboxedSdkView.orderProviderUiAboveClientUi()
کنترل می شود که یک setOnTop
می پذیرد.
وقتی setOnTop
true
باشد، هر android.view.MotionEvent
در SandboxedSdkView
به SDK ارسال میشود. در صورت false
، این موارد برای ناشر ارسال می شود. به طور پیشفرض، رویدادهای حرکتی به SDK ارسال میشوند.
ناشران معمولاً نیازی به تغییر ترتیب Z پیشفرض بازدیدهای تبلیغاتی ندارند. با این حال، هنگام نمایش رابط کاربری که یک تبلیغ را پوشش میدهد، مانند یک منوی کشویی، ترتیب Z باید به طور موقت از حالت پیشفرض برگردانده شود و پس از حذف عنصر UI پوشش دهنده، بازیابی شود. ما در حال بررسی راههایی برای خودکارسازی این فرآیند در کتابخانه UI مشتری هستیم.
پیمایش
وقتی رابط کاربری تبلیغات به Z-بالای پنجره ناشر سفارش داده می شود، MotionEvents
از رابط کاربری تبلیغات به SDK ارسال می شود. حرکات اسکرول و پرت کردن که در رابط کاربری آگهی شروع شده اند، رفتار خاصی دارند:
- حرکات حرکتی عمودی و پرت کردن به کانتینر ناشر ارسال می شود و توسط آن مدیریت می شود. زمانی که محفظه ناشر که رابط کاربری تبلیغات در آن قرار می گیرد، به صورت عمودی قابل پیمایش باشد، UX خوبی را فراهم می کند. این کار نیازی به کار اضافی در SDK یا ناشر ندارد.
- حرکات اسکرول افقی و پرت کردن به SDK ارسال شده و توسط آن مدیریت می شود. هنگامی که خود رابط کاربری تبلیغاتی به صورت افقی قابل پیمایش باشد (مانند چرخ فلک تبلیغات) این UX خوبی ارائه می دهد.
راهنمای پیاده سازی
SDK باید موارد زیر را اجرا کند:
-
SandboxedUiAdapter
: در پاسخ به یک API تعریفشده توسط SDK، مانندloadAd
، به ناشر برگردانده میشود. متدopenSession()
این پیاده سازی باید برای ایجاد یک درخواست تبلیغ به سرورهای SDK و تهیه نمای تبلیغ برای آن درخواست استفاده شود. -
Session**
: این در پاسخ به تماسSandboxedUiAdapter.openSession
برگردانده می شود. این روشی را برای کتابخانه سرویس گیرنده فراهم می کند تا رابط کاربری تبلیغات را به دست آورد و در مورد تغییرات این API به SDK اطلاع دهد. تمام متدهایSession
باید در اینجا پیاده سازی شوند.
ناشر باید موارد زیر را انجام دهد:
- یک
SandboxedSdkView
، از طریق XML یا برنامهنویسی ایجاد کنید. - برای مشاهده تغییرات در رابط کاربری، یک
SandboxedSdkUiSessionStateChangedListener
بهSandboxedSdkView
ضمیمه کنید. - یک SDK ارائه شده
SandboxedUiAdapter
بهSandboxedSdkView
وصل کنید. -
SandboxedSdkView
طبق معمول به پنجره اضافه کنید و به کتابخانه مشتری اجازه دهید تا از ایجاد و نگهداری جلسه UI با SDK مراقبت کند. - در زمان های مناسب، به تغییرات وضعیت گزارش شده توسط
SandboxedSdkUiSessionChangedListener
واکنش نشان دهید. به عنوان مثال، اگر SDK به طور غیرمنتظره جلسه را ببندد، ناشر می تواندSandboxedSdkView
با یک تصویر ثابت جایگزین کند یا آن را از سلسله مراتب مشاهده خود حذف کند. - هنگام انجام انتقالهایی که ممکن است رابط کاربری تبلیغات را پوشش دهند، مانند منوی کشویی، به طور موقت
orderProviderUiAboveClientUi
تا رابط کاربری آگهی در زیر پنجره ناشر قرار گیرد. پس از حذف منوی کشویی،orderProviderUiAboveClientUi
بهtrue
فراخوانی کنید.
آینده APIهای پلتفرم
هنگامی که کتابخانههای رابط کاربری وارد بتا شدند، قصد داریم APIهای پلتفرم زمان اجرا SDK مربوط به ارائه رابط کاربری، یعنی SdkSandboxManager.requestSurfacePackage()
و SandbxedSdkProvider.getView()
را منسوخ کنیم.
سوالات باز
- آیا موارد رایج تری برای استفاده از رابط کاربری تبلیغاتی وجود دارد که کتابخانه های رابط کاربری باید به طور خودکار آنها را مدیریت کنند؟
- از کدام چارچوبهای رابط کاربری برای نمایش رابط کاربری تبلیغات استفاده میکنید، آیا مشکلاتی را در ادغام کتابخانههای رابط کاربری با این چارچوبها پیشبینی میکنید؟
- آیا رابط کاربری تبلیغاتی قابل پیمایش قرار داده شده در یک محفظه ناشر قابل پیمایش، مورد استفاده رایج شماست؟ جهت حرکت پیمایش برای رابط کاربری تبلیغات و ظرف در این مورد چگونه است؟ وقتی کاربر پیمایشی را در رابط کاربری تبلیغات شروع می کند، چه رفتاری را انتظار دارید؟