AdSelectionManager

دریافت کنید

public static AdSelectionManager get (Context context)

روش کارخانه برای ایجاد یک نمونه از AdSelectionManager.

getAdSelectionData

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

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

تبلیغات مخاطب سفارشی باید دارای ad_render_id باشند تا واجد شرایط جمع آوری شوند.

برای نحوه پردازش نتایج انتخاب آگهی اجرا شده در سمت سرور با حباب ایجاد شده توسط این API، به AdSelectionManager#persistAdSelectionResult مراجعه کنید.

خروجی توسط گیرنده ارسال می شود، که یا یک GetAdSelectionDataOutcome را برای اجرای موفقیت آمیز برمی گرداند، یا یک Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای اجرای انتخاب آگهی دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر TimeoutException پرتاب شود، زمانی ایجاد می‌شود که در حین مناقصه، امتیازدهی یا فرآیند انتخاب کلی برای یافتن آگهی برنده، با مهلت زمانی مواجه می‌شویم.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

persistAdSelectionResult

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

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

برای نحوه ایجاد یک حباب رمزگذاری شده برای اجرای انتخاب آگهی در سمت سرور، به AdSelectionManager#getAdSelectionData مراجعه کنید.

خروجی توسط گیرنده ارسال می‌شود، که یا AdSelectionOutcome را برای اجرای موفقیت‌آمیز برمی‌گرداند، یا Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای اجرای انتخاب آگهی دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر TimeoutException پرتاب شود، زمانی ایجاد می‌شود که در حین مناقصه، امتیازدهی یا فرآیند انتخاب کلی برای یافتن آگهی برنده، با مهلت زمانی مواجه می‌شویم.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

گزارش رویداد

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

به سرویس اطلاع می دهد که یک رویداد تبلیغاتی جدید برای گزارش برای آگهی انتخاب شده توسط اجرای ad-selection مشخص شده توسط adSelectionId وجود دارد. رویداد تبلیغاتی هر رویدادی است که برای تبلیغ مرتبط با adSelectionId داده شده اتفاق می افتد. هیچ تضمینی در مورد زمان گزارش رویداد تبلیغاتی وجود ندارد. ممکن است گزارش رویداد به تأخیر بیفتد و گزارش‌ها دسته‌بندی شوند.

با استفاده از ReportEventRequest#getKey() ، این سرویس reportingUri که در registerAdBeacon ثبت شده است واکشی می کند. برای جزئیات بیشتر در مورد registerAdBeacon به مستندات reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) مراجعه کنید. سپس، این سرویس ReportEventRequest#getData() به بدنه درخواست درخواست POST متصل می کند و درخواست را ارسال می کند. بدنه درخواست POST دارای content-type text/plain خواهد بود و داده ها در charset=UTF-8 منتقل می شوند.

خروجی توسط گیرنده ارسال می شود، که یا یک Object خالی را برای اجرای موفقیت آمیز برمی گرداند، یا یک Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای گزارش رویداد آگهی دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.

رویدادها حداکثر یک بار به عنوان بهترین تلاش گزارش خواهند شد.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

ReportImpression

public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

به سرویس اطلاع می‌دهد که نمایش جدیدی برای گزارش برای آگهی انتخاب شده توسط اجرای ad-selection مشخص شده توسط adSelectionId وجود دارد. هیچ تضمینی در مورد اینکه چه زمانی برداشت گزارش می شود وجود ندارد. ممکن است گزارش برداشت به تأخیر بیفتد و گزارش‌ها دسته‌بندی شوند.

برای محاسبه URL گزارش فروشنده برنده، این سرویس منطق جاوا اسکریپت فروشنده را از AdSelectionConfig#getDecisionLogicUri() موجود در ReportImpressionRequest.getAdSelectionConfig() واکشی می کند. سپس، این سرویس یکی از توابع موجود در JS فروشنده به نام reportResult را اجرا می‌کند و سیگنال‌های روی دستگاه و همچنین ReportImpressionRequest#getAdSelectionConfig() به عنوان پارامترهای ورودی ارائه می‌کند.

تعریف تابع reportResult به صورت زیر است:

function reportResult(ad_selection_config, render_url, bid, contextual_signals) { return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url } }; }

برای محاسبه URL گزارش خریدار برنده، این سرویس منطق جاوا اسکریپت خریدار برنده را واکشی می کند که از طریق CustomAudience.getBiddingLogicUri() خریدار واکشی می شود. سپس، این سرویس یکی از توابع موجود در JS خریدار به نام reportWin را اجرا می‌کند که سیگنال‌های روی دستگاه، signals_for_buyer محاسبه‌شده توسط reportResult و فیلدهای خاص از ReportImpressionRequest#getAdSelectionConfig() را به عنوان پارامترهای ورودی ارائه می‌کند.

تعریف تابع reportWin به صورت زیر است:

function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer, contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results': {'reporting_url': reporting_url } }; }

علاوه بر این، خریداران و فروشندگان این امکان را دارند که برای دریافت گزارش رویدادهای تبلیغاتی خاص ثبت نام کنند. برای انجام این کار، آنها می توانند پلت فرم ارائه شده از تابع registerAdBeacon را در داخل reportWin و reportResult به ترتیب برای خریداران و فروشندگان فراخوانی کنند.

تعریف تابع registerBeacon این است:

function registerAdBeacon(beacons) ، که در آن beacons دستوری از رشته به جفت رشته است

برای هر رویداد تبلیغاتی، یک خریدار/فروشنده به گزارش‌های مربوط به آن علاقه دارد، آنها یک جفت event_key : event_reporting_uri را به beacons dict اضافه می‌کنند، جایی که event_key یک شناسه برای آن رویداد خاص است. زمانی که SDK reportEvent(ReportEventRequest, Executor, OutcomeReceiver) فراخوانی می‌کند، این event_key باید با ReportEventRequest#getKey() مطابقت داشته باشد. علاوه بر این، هر event_reporting_uri باید به درستی به یک Uri تجزیه شود. زمانی که SDK reportEvent(ReportEventRequest, Executor, OutcomeReceiver) فراخوانی می کند، Uri به آن گزارش می شود.

وقتی خریدار/فروشنده تمام جفت‌هایی را که می‌خواهند رویدادها را دریافت کنند اضافه کرد، می‌توانند registerAdBeacon(beacons) را فراخوانی کنند، جایی که beacons نام دیکتی است که جفت‌ها را به آن اضافه کرده‌اند.

registerAdBeacon در این شرایط یک TypeError ایجاد می کند:

1. registerAdBeacon بیش از یک بار فراخوانی می شود. اگر این خطا در reportWin/reportResult مشاهده شود، مجموعه اصلی جفت‌ها ثبت می‌شود.
2. registerAdBeacon دقیقاً 1 آرگومان dict ندارد.
3. محتویات آرگومان 1 dict همه جفت‌های String: String نیستند.

خروجی توسط receiver ارسال می شود، که یا یک Object خالی را برای اجرای موفقیت آمیز برمی گرداند، یا یک Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای گزارش نمایش دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.

برداشت ها حداکثر یک بار به عنوان بهترین تلاش گزارش می شوند.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

انتخاب تبلیغات

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

یک تبلیغ را از نتایج انتخاب های تبلیغاتی که قبلاً اجرا شده است انتخاب می کند.

ورودی adSelectionFromOutcomesConfig توسط Ads SDK ارائه می شود و شی AdSelectionFromOutcomesConfig از طریق تماس Binder منتقل می شود. به همین دلیل، اندازه کل این اشیاء به محدودیت های IPC اندروید محدود می شود. عدم انتقال AdSelectionFromOutcomesConfig باعث ایجاد یک TransactionTooLargeException می شود.

خروجی توسط گیرنده ارسال می‌شود، که یا AdSelectionOutcome را برای اجرای موفقیت‌آمیز برمی‌گرداند، یا Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

ورودی adSelectionFromOutcomesConfig شامل:

• Seller باید AdTechIdentifier ثبت شده باشد. در غیر این صورت، IllegalStateException پرتاب می شود.
• List of ad selection ids باید وجود داشته باشد و از تماس‌های selectAds(AdSelectionConfig, Executor, OutcomeReceiver) باشد که از همان برنامه نشات گرفته‌اند. در غیر این صورت، IllegalArgumentException برای اعتبار سنجی ورودی، فهرستی را که شناسه انتخاب آگهی را نقض می کند، افزایش می دهد.
• Selection logic URI که می تواند از طرحواره های HTTPS یا انتخاب آگهی از پیش ساخته شده پیروی کند.

  اگر URI از طرح HTTPS پیروی کند، میزبان باید با seller مطابقت داشته باشد. در غیر این صورت، IllegalArgumentException پرتاب می شود.

  URI های از پیش ساخته شده راهی برای جایگزینی یک منطق از پیش ساخته شده عمومی برای جاوا اسکریپت های مورد نیاز برای selectOutcome هستند. Uri از پیش ساخته شده برای این نقطه پایانی باید دنبال شود.

  • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

  اگر یک URI از پیش ساخته شده پشتیبانی نشده ارسال شود یا ویژگی URI از پیش ساخته شده توسط سرویس غیرفعال شود، IllegalArgumentException پرتاب می شود.

  برای <name> پشتیبانی شده و <script-generation-parameters> مورد نیاز AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri را ببینید.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای اجرای انتخاب آگهی دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر TimeoutException پرتاب شود، زمانی ایجاد می‌شود که در حین مناقصه، امتیازدهی یا فرآیند انتخاب کلی برای یافتن آگهی برنده، با مهلت زمانی مواجه می‌شویم.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

انتخاب تبلیغات

public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

فرآیند انتخاب آگهی را روی دستگاه اجرا می کند تا یک آگهی بازاریابی مجدد برای برنامه تماس گیرنده انتخاب شود.

ورودی adSelectionConfig توسط Ads SDK ارائه می شود و شی AdSelectionConfig از طریق تماس Binder منتقل می شود. به همین دلیل، اندازه کل این اشیاء به محدودیت های IPC اندروید محدود می شود. عدم انتقال AdSelectionConfig باعث ایجاد یک TransactionTooLargeException می شود.

ورودی adSelectionConfig حاوی Decision Logic Uri است که می تواند از طرحواره های HTTPS یا Ad Selection Prebuilt پیروی کند.

اگر URI از طرح HTTPS پیروی کند، میزبان باید با seller مطابقت داشته باشد. در غیر این صورت، IllegalArgumentException پرتاب می شود.

URI های از پیش ساخته شده راهی برای جایگزینی یک منطق از پیش ساخته شده عمومی برای جاوا اسکریپت های مورد نیاز برای scoreAds هستند. Uri از پیش ساخته شده برای این نقطه پایانی باید دنبال شود.

• ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

اگر یک URI از پیش ساخته شده پشتیبانی نشده ارسال شود یا ویژگی URI از پیش ساخته شده توسط سرویس غیرفعال شود، IllegalArgumentException پرتاب می شود.

برای <name> پشتیبانی شده و <script-generation-parameters> مورد نیاز AdSelectionConfig.Builder#setDecisionLogicUri را ببینید.

خروجی توسط گیرنده ارسال می‌شود، که یا AdSelectionOutcome را برای اجرای موفقیت‌آمیز برمی‌گرداند، یا Exception شامل نوع استثنا پرتاب شده و پیام خطای مربوطه است.

اگر IllegalArgumentException پرتاب شود، دلیل آن آرگومان ورودی نامعتبر است که API برای اجرای انتخاب آگهی دریافت کرده است.

اگر IllegalStateException با پیغام خطای "Failure of AdSelection Services" پرتاب شود، به دلیل خرابی داخلی سرویس انتخاب آگهی ایجاد می شود.

اگر TimeoutException پرتاب شود، زمانی ایجاد می‌شود که در حین مناقصه، امتیازدهی یا فرآیند انتخاب کلی برای یافتن آگهی برنده، با مهلت زمانی مواجه می‌شویم.

اگر LimitExceededException پرتاب شود، زمانی ایجاد می شود که بسته فراخوانی از محدودیت های نرخ مجاز فراتر رفته و درنگ شود.

اگر SecurityException پرتاب شود، زمانی ایجاد می شود که تماس گیرنده مجاز نباشد یا مجوز درخواست نشود.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

updateAdCounterHistogram

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

هیستوگرام شمارنده را برای تبلیغی که قبلاً با تماس با selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) انتخاب شده بود، به روز می کند.

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

هیستوگرام شمارنده را فقط می‌توان برای آگهی‌هایی که توسط adSelectionId مشخص شده به‌روزرسانی شده است، به‌روزرسانی کرد.

یک SecurityException از طریق outcomeReceiver برگردانده می شود اگر:

1. برنامه مجوزهای صحیح را در مانیفست خود اعلام نکرده است، یا
2. برنامه یا موجودیت شناسایی شده توسط callerAdTechIdentifier مجاز به استفاده از API نیست.

اگر تماس از دریچه گاز API برنامه تماس فراتر رود، یک LimitExceededException از طریق outcomeReceiver برگردانده می شود.

در تمام موارد خرابی دیگر، outcomeReceiver یک Object خالی را برمی گرداند. توجه داشته باشید که برای حفظ حریم خصوصی کاربر، خطاهای داخلی از طریق استثنا ارسال نمی شود.
به AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE نیاز دارد.ACCESS_ADSERVICES_CUSTOM_AUDIENCE