APIهای ارائه رابط کاربری SDK Runtime، APIهای ارائه رابط کاربری SDK Runtime، APIهای ارائه رابط کاربری SDK Runtime

SDK Runtime اجازه می دهد تا SDK های تبلیغاتی در یک محیط sandbox اجرا شوند و از دسترسی آنها به سلسله مراتب مشاهده ناشر جلوگیری می کند. برای نمایش تبلیغات، این پلتفرم یک SandboxedSdkProvider.getView API را در اختیار SDK قرار می دهد تا یک نمای تبلیغاتی به دست آورد، و آن را به عنوان یک SurfacePackage بسته بندی می کند تا از طریق IPC (ارتباط بین فرآیندی) به برنامه مشتری ارسال شود. این چند اشکال دارد که در ادامه به آنها پرداخته می شود. این سند سپس یک کتابخانه Jetpack پیشنهادی را ارائه می کند که برای رسیدگی به این چالش ها ساخته شده است.

دلیل تقویت APIهای پلتفرم

APIهای چارچوب برای انعطاف‌پذیری طراحی شده‌اند و وظیفه ایجاد یک کانال جانبی را برای ارائه UI تا برنامه و SDK واگذار می‌کنند. این کانال جانبی کارهای زیر را انجام می دهد:

  1. به SDK اجازه می‌دهد چندین بازدید از آگهی را در طول عمر خود مدیریت کند و بفهمد پس از ایجاد رابط کاربری تبلیغاتی توسط SDK چه اتفاقی می‌افتد.
  2. ایجاد و اتصال محتوا را جدا می‌کند. استفاده از کانال جانبی به SDK اجازه می‌دهد تا یک شی مطابق با درخواست آگهی را به برنامه (محتوا) برگرداند، که هر زمان که برنامه مناسب بداند می‌تواند به محفظه آگهی متصل شود.
  3. ساختارهای پلتفرم زیربنایی را که برای نشان دادن رابط کاربری در سراسر فرآیندها استفاده می شود، انتزاع می کند. (این پلتفرم در حال حاضر از SurfaceControlViewhost استفاده می کند و یک SurfacePackage از آن تولید می کند.)
  4. SDK های تبلیغات را در زمان اجرای SDK فعال می کند تا به صورت خودکار اعلان ها را هنگام تغییر رابط کاربری ظرف تبلیغات دریافت کنند. اگر ناشر طرح‌بندی ظرف تبلیغات را تغییر دهد، SDK از این تغییرات بی‌اطلاع می‌ماند، مگر اینکه ناشر صریحاً با یک API تماس بگیرد تا به آن اطلاع دهد.
  5. تغییر اندازه رابط کاربری تبلیغات و ظرف تبلیغات را بدون هیچ گونه jank قابل مشاهده برای کاربر همگام می کند.
  6. سازگاری به عقب را به طور خودکار مدیریت می کند. SurfacePackage قبل از سطح API 30 در دسترس نیست. به‌علاوه، در دستگاه‌هایی که زمان اجرای SDK وجود ندارد و SDK برای ناشر فرآیندی محلی است، ایجاد یک SurfacePackage برای یک آگهی زمانی که می‌توان نما را مستقیماً از SDK دریافت کرد، بیهوده است. کانال جانبی این پیچیدگی را از کد توسعه‌دهنده SDK و برنامه حذف می‌کند.
  7. رابط کاربری تبلیغات را قادر می سازد تا به طور یکپارچه با 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 ارائه رابط کاربری SDK Runtime را نشان می دهد.
روابط بین APIهای ارائه رابط کاربری SDK Runtime.

برای جزئیات بیشتر در مورد این APIها ، اسناد مرجع privacysandbox-ui را بخوانید.

جریان را کنترل کنید

نمودارهای زیر تعامل بین کتابخانه های UI مشتری و ارائه دهنده را در سناریوهای مختلف نشان می دهد:

نمودار قبلی نشان می‌دهد که چگونه ناشر می‌تواند یک SandboxedSdkView به صورت برنامه‌نویسی یا از طریق XML خود ایجاد کند و آن را به SdkSandboxUiAdapter که از SDK از طریق یک API تعریف‌شده توسط SDK به دست آمده است، متصل کند. برای مشاهده همه تغییرات حالت رابط کاربری، ناشر باید قبل از پیوست کردن SdkSandboxUiAdapter SandboxedSdkUiSessionStateChangedListener به SandboxedSdkView اضافه کند.

تصویری که فرآیند جلسه باز را نشان می دهد.
UI را از SDK دریافت کنید.

این نمودار نشان می‌دهد که اگر فعالیت ناشر تغییرات پیکربندی را کنترل کند، کتابخانه سرویس گیرنده از ارسال تغییر پیکربندی به SDK مراقبت می‌کند، بنابراین آنها می‌توانند رابط کاربری خود را بر این اساس به‌روزرسانی کنند. به عنوان مثال، زمانی که کاربر دستگاه را بچرخاند و ناشر مدیریت تغییرات پیکربندی در فعالیت خود را با تنظیم android:configChanges=["orientation"] اعلام کند، این جریان می تواند فعال شود.

تغییر رابط کاربری ایجاد شده توسط ناشر.

این نمودار نشان می‌دهد که چگونه SDK می‌تواند با استفاده از روش‌هایی در SessionClient درخواست تغییر در ظرف آگهی دهد. این API زمانی فعال می‌شود که SDK می‌خواهد اندازه آگهی را تغییر دهد و به ناشر نیاز دارد تا اندازه ظرف آگهی را برای سازگاری با ابعاد جدید تغییر دهد. این ممکن است در پاسخ به تعامل کاربر، مانند mraid.resize() رخ دهد.

تغییر رابط کاربری ایجاد شده با SDK.

این نمودار نشان می دهد که چگونه وقتی 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 ارسال می شود. حرکات اسکرول و پرت کردن که در رابط کاربری آگهی شروع شده اند، رفتار خاصی دارند:

  1. حرکات حرکتی عمودی و پرت کردن به کانتینر ناشر ارسال می شود و توسط آن مدیریت می شود. زمانی که محفظه ناشر که رابط کاربری تبلیغات در آن قرار می گیرد، به صورت عمودی قابل پیمایش باشد، UX خوبی را فراهم می کند. این کار نیازی به کار اضافی در SDK یا ناشر ندارد.
  2. حرکات اسکرول افقی و پرت کردن به SDK ارسال شده و توسط آن مدیریت می شود. هنگامی که خود رابط کاربری تبلیغاتی به صورت افقی قابل پیمایش باشد (مانند چرخ فلک تبلیغات) این UX خوبی ارائه می دهد.

راهنمای پیاده سازی

SDK باید موارد زیر را اجرا کند:

  • SandboxedUiAdapter : در پاسخ به یک API تعریف‌شده توسط SDK، مانند loadAd ، به ناشر برگردانده می‌شود. متد openSession() این پیاده سازی باید برای ایجاد یک درخواست تبلیغ به سرورهای SDK و تهیه نمای تبلیغ برای آن درخواست استفاده شود.
  • Session** : این در پاسخ به تماس SandboxedUiAdapter.openSession برگردانده می شود. این روشی را برای کتابخانه سرویس گیرنده فراهم می کند تا رابط کاربری تبلیغات را به دست آورد و در مورد تغییرات این API به SDK اطلاع دهد. تمام متدهای Session باید در اینجا پیاده سازی شوند.

ناشر باید موارد زیر را انجام دهد:

  1. یک SandboxedSdkView ، از طریق XML یا برنامه‌نویسی ایجاد کنید.
  2. برای مشاهده تغییرات در رابط کاربری، یک SandboxedSdkUiSessionStateChangedListener به SandboxedSdkView ضمیمه کنید.
  3. یک SDK ارائه شده SandboxedUiAdapter به SandboxedSdkView وصل کنید.
  4. SandboxedSdkView طبق معمول به پنجره اضافه کنید و به کتابخانه مشتری اجازه دهید تا از ایجاد و نگهداری جلسه UI با SDK مراقبت کند.
  5. در زمان های مناسب، به تغییرات وضعیت گزارش شده توسط SandboxedSdkUiSessionChangedListener واکنش نشان دهید. به عنوان مثال، اگر SDK به طور غیرمنتظره جلسه را ببندد، ناشر می تواند SandboxedSdkView با یک تصویر ثابت جایگزین کند یا آن را از سلسله مراتب مشاهده خود حذف کند.
  6. هنگام انجام انتقال‌هایی که ممکن است رابط کاربری تبلیغات را پوشش دهند، مانند منوی کشویی، به طور موقت orderProviderUiAboveClientUi تا رابط کاربری آگهی در زیر پنجره ناشر قرار گیرد. پس از حذف منوی کشویی، orderProviderUiAboveClientUi به true فراخوانی کنید.

آینده APIهای پلتفرم

هنگامی که کتابخانه‌های رابط کاربری وارد بتا شدند، قصد داریم APIهای پلتفرم زمان اجرا SDK مربوط به ارائه رابط کاربری، یعنی SdkSandboxManager.requestSurfacePackage() و SandbxedSdkProvider.getView() را منسوخ کنیم.

سوالات باز

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