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

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

منطق افزایش APIهای پلتفرم

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

  1. به SDK اجازه می‌دهد تا نمایش‌های متعدد تبلیغات را در طول عمرشان مدیریت کند و بفهمد که پس از ایجاد رابط کاربری تبلیغ توسط SDK، چه اتفاقی برای آن می‌افتد.
  2. ایجاد نما و اتصال محتوا را از هم جدا می‌کند. استفاده از کانال جانبی به SDK اجازه می‌دهد تا شیء‌ای را که مطابق با درخواست تبلیغ به برنامه (محتوا) است، برگرداند، که می‌تواند هر زمان که برنامه مناسب بداند به کانتینر تبلیغ متصل شود.
  3. ساختارهای زیربنایی پلتفرم که برای نمایش رابط کاربری در فرآیندها استفاده می‌شوند را خلاصه می‌کند. (این پلتفرم در حال حاضر از یک SurfaceControlViewhost استفاده می‌کند و یک SurfacePackage از آن تولید می‌کند.)
  4. SDKهای تبلیغاتی را در زمان اجرای SDK فعال می‌کند تا هنگام تغییر رابط کاربری ظرف تبلیغ، به‌طور خودکار اعلان دریافت کنند. اگر ناشری طرح‌بندی ظرف تبلیغ را تغییر دهد، SDK از این تغییرات بی‌اطلاع می‌ماند، مگر اینکه ناشر به‌طور صریح یک API را برای اطلاع‌رسانی فراخوانی کند.
  5. تغییر اندازه رابط کاربری تبلیغ و محفظه تبلیغ را بدون هیچ گونه اختلال قابل مشاهده برای کاربر، همگام‌سازی می‌کند.
  6. سازگاری با نسخه‌های قبلی را به طور خودکار مدیریت می‌کند. SurfacePackage قبل از سطح API 30 در دسترس نیست. علاوه بر این، در دستگاه‌هایی که زمان اجرای SDK وجود ندارد و SDK به صورت محلی برای ناشر پردازش می‌شود، ایجاد SurfacePackage برای یک تبلیغ زمانی که می‌توان مستقیماً از SDK به آن دسترسی داشت، بی‌فایده است. کانال جانبی این پیچیدگی را از SDK و کد توسعه‌دهنده برنامه جدا می‌کند.
  7. رابط کاربری تبلیغات را قادر می‌سازد تا به طور یکپارچه با Composables ادغام شود. توسعه‌دهندگان Jetpack Compose که با نماها کار نمی‌کنند، می‌توانند همچنان رابط کاربری تولید شده توسط توسعه‌دهنده SDK را که هنوز با نماها کار می‌کند، میزبانی کنند.

کتابخانه‌های رابط کاربری

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

سه کتابخانه رابط کاربری وجود دارد: هسته ، کلاینت و ارائه دهنده . کتابخانه هسته، رابط‌های مورد استفاده توسط کتابخانه‌های کلاینت و ارائه دهنده را فراهم می‌کند. ارائه دهنده رابط کاربری (معمولاً SDK) به کتابخانه ارائه دهنده بستگی دارد و مصرف کننده رابط کاربری (معمولاً ناشر) به کتابخانه کلاینت وابسته است. کتابخانه‌های کلاینت و ارائه دهنده با هم، کانال جانبی مورد نیاز برای ایجاد و نگهداری یک جلسه رابط کاربری را تشکیل می‌دهند.

API ها

API های مربوط به ارائه رابط کاربری SDK Runtime به شرح زیر است:

SandboxedUiAdapter : توسط SDK ایجاد شده و راهی برای دریافت محتوا جهت نمایش در رابط کاربری ناشر فراهم می‌کند.

SandboxedSdkView : این یک کانتینر است که توسط ناشر ایجاد می‌شود و محتوای دریافتی از طریق SandboxedUiAdapter را در خود نگه می‌دارد.

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

SessionClient : توسط کتابخانه کلاینت ایجاد می‌شود و انتهای ناشر تونل ارتباطی بین SDK و ناشر را تشکیل می‌دهد.

SandboxedSdkUiSessionStateChangedListener : توسط ناشر ایجاد می‌شود. شنونده‌ای برای تغییرات در وضعیت جلسه رابط کاربری مرتبط با SandboxedSdkView .

تصویری که روابط API ارائه رابط کاربری زمان اجرا SDK را نشان می‌دهد.
روابط بین APIهای ارائه رابط کاربری SDK Runtime.

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

جریان کنترل

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

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

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

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

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

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

تغییر رابط کاربری آغاز شده توسط SDK.

این نمودار نشان می‌دهد که چگونه جلسه زمانی که SandboxedSdkView از پنجره جدا می‌شود، بسته می‌شود. همچنین می‌توان جلسه را در هر نقطه‌ای (مثلاً زمانی که کاربر اتصال به شبکه را از دست می‌دهد) توسط SDK با فراخوانی SessionClient.onSessionError() بست.

بستن جلسه رابط کاربری.

سفارش Z

کتابخانه رابط کاربری کلاینت به صورت داخلی از یک SurfaceView برای میزبانی رابط کاربری SDK استفاده می‌کند. SurfaceView می‌تواند از Z order برای نمایش رابط کاربری خود در بالای پنجره ناشر یا در زیر آن استفاده کند. این امر توسط متد SandboxedSdkView.orderProviderUiAboveClientUi() کنترل می‌شود که یک مقدار بولی setOnTop می‌پذیرد.

وقتی setOnTop true باشد، هر android.view.MotionEvent در SandboxedSdkView به SDK ارسال می‌شود. وقتی false ، این رویدادها به publisher ارسال می‌شوند. به طور پیش‌فرض، رویدادهای حرکتی به SDK ارسال می‌شوند.

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

پیمایش

وقتی رابط کاربری تبلیغ به صورت Z-بالای پنجره ناشر مرتب می‌شود، MotionEvents از رابط کاربری تبلیغ به SDK ارسال می‌شود. حرکات اسکرول و پرتاب که در رابط کاربری تبلیغ آغاز می‌شوند، به طور ویژه مورد توجه قرار می‌گیرند:

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

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

SDK باید موارد زیر را پیاده‌سازی کند:

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

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

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

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

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

سوالات باز

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