پشتیبانی از میانجیگری در SDK Runtime

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

این سند تغییرات کلیدی در جریان کار میانجی در زمان اجرا SDK را تشریح می کند. موضوعات زیر را پوشش می دهد:

• تفاوت‌های بین جریان‌های میانجی‌گری قبلی و پشتیبانی فعلی میانجی‌گری SDK Runtime
• اقدامات راه اندازی برای گردش کار میانجی در زمان اجرا SDK و مراحل مختلف انتقال
• راهنمایی در مورد نحوه رسیدگی به سناریوهایی که همه SDK ها به Runtime منتقل نشده اند

پشتیبانی از تبلیغات میانجی در زمان اجرا SDK از AGP 8.5 و از نسخه های زیر کتابخانه های SDK Runtime Jetpack در دسترس است:

کتابخانه Androidx	نسخه
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

واژه نامه

عبارات زیر برای درک میانجیگری در SDK Runtime کلیدی هستند:

• Runtime-enabled SDK (RE SDK): یک SDK ساخته شده برای اجرا در محیط SDK Runtime و برقراری ارتباط با برنامه از طریق ارتباطات بین فرآیندی (IPC).
• Runtime-Aware SDK (RA SDK): یک SDK غیر فعال با زمان اجرا، که به صورت ایستا به برنامه پیوند داده شده است، که ممکن است حاوی کد SDK موجود شما و همچنین کد جدیدی برای فراخوانی به SDK فعال با زمان اجرا شما باشد.
• SDK درون‌برنامه‌ای: یک SDK که به‌صورت ایستا با برنامه مرتبط است و هیچ اطلاعی از زمان اجرا SDK ندارد. این ممکن است یک شبکه تبلیغاتی باشد که به زمان اجرا SDK یا آداپتور سفارشی ناشر منتقل نشده باشد.
• Mediator: SDK میانجی‌گری تبلیغاتی که با تعامل با سایر SDK‌های شبکه تبلیغاتی، سرویس میانجی را روی دستگاه ارائه می‌کند.
• واسطه: SDK شبکه تبلیغاتی که توسط Mediator برای ارائه و ارائه یک تبلیغ فراخوانی می شود.
• آداپتور میانجیگری: SDKهایی که توسط Mediator SDK برای ارائه ترجمه رابط API برای تعامل با SDKهای واسطه مختلف، که معمولاً توسط واسطه ارائه می‌شوند، استفاده می‌شوند. اینها می توانند زمان اجرا آگاه یا زمان اجرا ناآگاه باشند.

جریان‌های میانجی‌گری معمولی

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

جریان‌هایی که ما توضیح می‌دهیم، نسخه ساده‌شده‌ای از میانجیگری روی دستگاه را با چند SDK شبکه تبلیغاتی نشان می‌دهند، و به عنوان مبنایی برای بحث در مورد تغییرات مورد نیاز برای سازگار کردن سفرهای میانجی با زمان اجرای SDK عمل می‌کنند.

با توجه به تنوع در اجرای جریان میانجیگری، ما بر دو جریان اصلی زیر تمرکز می کنیم:

• اولیه سازی (از جمله کشف شبکه های تبلیغاتی و ارتباطات)
• ارائه رابط کاربری تبلیغاتی (UI).

مقداردهی اولیه

موارد زیر یک مقدار اولیه اولیه، کشف شبکه تبلیغاتی و جریان ارتباطی را نشان می دهد:

1. برنامه مشتری واسطه را راه اندازی می کند
2. میانجی واسطه ها و تطبیق دهنده های مربوطه را کشف و مقداردهی اولیه می کند
3. واسطه از آداپتورهای خود برای برقراری ارتباط با هر واسطه استفاده می کند
4. برنامه مشتری از میانجی درخواست می کند که یک تبلیغ را بارگیری کند
5. برنامه مشتری از میانجی درخواست می کند که این آگهی را نشان دهد

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

ارائه رابط کاربری تبلیغات

وقتی نوبت به ارائه آگهی بعد از درخواست نهایی در مرحله قبل می‌شود، جریان به نوع تبلیغ بستگی دارد:

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

میانجیگری در زمان اجرا SDK جریان دارد

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

• هم واسطه و هم واسطه در SDK Runtime: RE mediatee هستند
• واسطه در زمان اجرا SDK است و واسطه در برنامه است: واسطه درون برنامه

میانجی RE

نمودار معماری زیر نمای کلی سطح بالایی از تعامل SDK های فعال در زمان اجرا (RE) و زمان اجرا آگاه (RA)، آداپتورهای میانجی RE و RE SDK های واسطه را نشان می دهد.

آداپتورهای میانجی باید در همان فرآیندی باشند که واسطه ای که با آن در ارتباط هستند، بنابراین باید به زمان اجرای SDK نیز مهاجرت کنند.

شکل 1. هم میانجی و هم واسطه، RE SDK هستند.

مقداردهی اولیه

هنگام در نظر گرفتن مقداردهی اولیه، کشف و ارتباط میانجی و واسطه فعال با زمان اجرا، جریان این مراحل را دنبال می کند:

1. برنامه (یا RA SDK) SDK واسطه را با استفاده از SdkSandboxManager#loadSdk بارگیری و مقداردهی اولیه می کند.
2. در طول اولیه سازی، SDK واسطه هر واسطه مورد نیاز در زمان اجرا SDK را با استفاده از SdkSandboxController#loadSdk بارگیری و مقداردهی اولیه می کند.
3. RE SDK می‌تواند با فراخوانی SdkSandboxController#getSandboxedSdks همه SDK‌های بارگذاری‌شده را در Runtime کشف کند.

شکل 2. جریان برای مقداردهی اولیه یک واسطه RE.

توجه: از کلاس‌های *Compat Runtime Manager و Controller برای اطمینان از سازگاری SDK فعال با زمان اجرا استفاده کنید.

ارائه رابط کاربری تبلیغات

بخش زیر بارگذاری بنرها و تبلیغات تمام صفحه از یک واسطه RE را پوشش می دهد.

تبلیغات بنری RE Mediatee

با توجه به درخواست برنامه برای بارگذاری یک آگهی تبلیغاتی، جریان کامل رندر به شرح زیر است:

1. میانجی واسطه برنده این آگهی را انتخاب می کند.
2. واسطه یک SandboxedUiAdapter از میانجی دریافت می کند.
3. واسطه UiAdapter را به برنامه ارسال می کند.

شکل 3. جریان برای تکمیل رندر یک آگهی تبلیغاتی از یک واسطه RE.

درباره استفاده از SandboxedUiAdapter و کتابخانه SDK Runtime UI بیشتر بیاموزید.

پوشش های تبلیغاتی بنری

اگر واسطه‌ها بخواهند یک همپوشانی به آگهی اضافه کنند، باید جریان را به صورت زیر تغییر دهند:

1. واسطه با پوشش آن و SandboxedSdkView یک طرح‌بندی ایجاد می‌کند.
2. میانجی واسطه برنده این آگهی را انتخاب می کند.
3. واسطه یک SandboxedUiAdapter از میانجی دریافت می کند.
4. واسطه، UiAdapter واسطه را روی SandboxedSdkView تنظیم می کند.
5. میانجی نمای پر شده را با برنامه به اشتراک می گذارد.

جریان برای همپوشانی یک نما بر روی یک آگهی تبلیغاتی به دست آمده از یک واسطه RE.

تبلیغات تمام صفحه RE Mediatee

با توجه به درخواستی از برنامه برای بارگیری یک تبلیغ تمام صفحه، جریان این مراحل را دنبال می کند:

1. برنامه (یا RA SDK) یک SdkActivityLauncher با درخواست بارگذاری آگهی به واسطه ارسال می کند.
   1. مشتری می تواند ایجاد فعالیت ها را با استفاده از یک محمول محدود کند.
2. میانجی واسطه برنده این آگهی را انتخاب می کند.
3. واسطه از میانجی درخواست می‌کند تا یک آگهی را بارگیری کند و SdkActivityLauncher را از برنامه ارسال کند.
4. واسطه یک کنترل کننده فعالیت را ثبت می کند و یک نشانه شناسه برای فعالیت ثبت شده دریافت می کند.
5. واسطه از SdkActivityLauncher برای درخواست شروع فعالیت با استفاده از این نشانه استفاده می کند.
6. اگر محمول برنامه کلاینت اجازه دهد، SDK Runtime این فعالیت را در فرآیند اختصاصی شروع می کند.

شکل 4. نمودار جریان نشان می دهد که چگونه یک تبلیغ تمام صفحه با واسطه را از یک واسطه RE بارگیری کنید.

توجه: تمام رویدادهای چرخه حیات فعالیت با استفاده از ActivityHolder که هنگام ثبت کنترل کننده فعالیت استفاده می کرد، در دسترس واسطه قرار می گیرد.

درباره پشتیبانی Activity برای تبلیغات تمام صفحه در SDK Runtime بیشتر بیاموزید.

میانجی درون برنامه

نمودار معماری زیر نمای کلی سطح بالایی از تعامل SDKهای RE و RA واسطه، آداپتورهای میانجی که از زمان اجرا SDK اطلاعی ندارند، و SDKهای واسطه که به طور ایستا به برنامه مرتبط هستند (همچنین زمان اجرا بدون اطلاع) را نشان می دهد.

شکل 5. واسطه به طور ایستا به برنامه مرتبط است، حتی اگر از RE SDK آگاه باشد.

مقداردهی اولیه

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

این ثبت باید با استفاده از API میانجی قابل دسترسی باشد، اما جزئیات پیاده سازی به صلاحدید هر واسطه واگذار می شود. ما این API را MediationSandboxedSdk#registerInAppMediatee می نامیم.

هنگام در نظر گرفتن مقداردهی اولیه، کشف و ارتباط یک SDK میانجی RE و SDK های واسطه درون برنامه، این جریان مراحل زیر را دنبال می کند:

1. برنامه SDK آگاه از زمان اجرا واسطه را بارگیری و مقداردهی اولیه می کند.
2. RA SDK واسطه:
   1. RE SDK واسطه را با استفاده از SdkSandboxManager#loadSdk راه اندازی می کند.
   2. همه SDK های واسطه درون برنامه را راه اندازی می کند.
   3. با استفاده از API ارائه شده توسط RE SDK، MediationSandboxedSdk#registerInAppMediate ، SDK های واسطه درون برنامه را کشف و ثبت می کند.

علاوه بر ثبت همه SDK های واسطه درون برنامه، RE SDK واسطه می تواند با استفاده از SdkSandboxController#getSandboxedSdks همه SDK های بارگذاری شده در زمان اجرا SDK را کشف کند.

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

ارائه رابط کاربری تبلیغات

بخش زیر بارگذاری بنرها و تبلیغات تمام صفحه از یک واسطه درون برنامه را پوشش می دهد.

تبلیغات بنری واسطه درون برنامه ای

با توجه به درخواست برنامه برای بارگذاری یک آگهی تبلیغاتی، جریان کامل رندر به شرح زیر است:

1. SDK آگاه از زمان اجرا، درخواست برنامه را به SDK فعال با زمان اجرا ارسال می‌کند.
2. RE SDK میانجی واسطه مربوطه را انتخاب می کند.
3. RE SDK واسطه، ارجاع به واسطه را بازیابی می‌کند و درخواست بارگذاری آگهی از طریق RA SDK می‌کند.
4. RA SDK یک نمای از واسطه درون برنامه دریافت می کند.
5. RA SDK یک SandboxedUiAdapter برای نمای دریافتی ایجاد می کند.
6. RA SDK UiAdapter را به RE SDK ارسال می کند.
7. RE SDK UiAdapter را به برنامه ارسال می کند.

احتیاط: از آنجایی که این SandboxedUiAdapter از فرآیند برنامه دریافت می‌شود، توصیه نمی‌کنیم هم‌پوشانی به این View اضافه کنید زیرا ممکن است منجر به تاخیر، عملکرد و مشکلات رفتاری شود.

شکل 7. توجه داشته باشید که هنگام دریافت آن از یک واسطه درون برنامه، واسطه نباید نماها را روی V1 همپوشانی کند.

تبلیغات تمام صفحه واسطه درون برنامه ای

با توجه به درخواستی از برنامه برای بارگیری یک تبلیغ تمام صفحه، جریان این مراحل را دنبال می کند:

1. این برنامه یک SdkActivityLauncher با درخواست بارگذاری آگهی به RA SDK واسطه ارسال می کند.
   1. مشتری می تواند ایجاد فعالیت ها را با استفاده از یک محمول محدود کند.
2. RA SDK واسطه درخواست برنامه را به RE SDK آن ارسال می کند.
3. RE SDK واسطه:
   1. واسطه مربوطه را انتخاب می کند.
   2. ارجاع به واسطه درون برنامه را بازیابی می کند.
   3. درخواست بارگذاری آگهی از طریق RA SDK.
4. RA SDK از میانجی درخواست می‌کند تا آگهی را بارگیری کند.
5. واسطه فعالیت را مستقیماً شروع می کند. محمول برنامه رعایت نمی شود.

شکل 8. محمول توسط واسطه درون برنامه نادیده گرفته می شود.

توجه: همه رویدادهای مربوط به فعالیت مانند قبل از زمان اجرای SDK در دسترس واسطه هستند.

مشارکت کنید و بازخورد را به اشتراک بگذارید

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