راهنمای توسعه دهنده API مخاطبان محافظت شده

همانطور که مستندات Privacy Sandbox را در اندروید مطالعه می‌کنید، از دکمه Developer Preview یا Beta برای انتخاب نسخه برنامه‌ای که با آن کار می‌کنید استفاده کنید، زیرا دستورالعمل‌ها ممکن است متفاوت باشند.

رابط برنامه‌نویسی کاربردی (API) مخاطب محافظت‌شده در اندروید (که قبلاً با نام FLEDGE شناخته می‌شد) شامل رابط برنامه‌نویسی کاربردی مخاطب سفارشی و رابط برنامه‌نویسی کاربردی انتخاب تبلیغات است. پلتفرم‌های فناوری تبلیغات و تبلیغ‌کنندگان می‌توانند از این رابط‌های برنامه‌نویسی کاربردی برای ارائه تبلیغات سفارشی‌شده بر اساس تعامل قبلی برنامه استفاده کنند که اشتراک‌گذاری شناسه‌ها را در برنامه‌ها و اشتراک‌گذاری اطلاعات تعامل برنامه کاربر با اشخاص ثالث را محدود می‌کند.

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

رابط برنامه‌نویسی کاربردی انتخاب تبلیغات (Ad Selection API) چارچوبی را فراهم می‌کند که به چندین توسعه‌دهنده اجازه می‌دهد تا برای یک مخاطب سفارشی، یک حراج محلی برگزار کنند. برای دستیابی به این هدف، سیستم تبلیغات مرتبط با مخاطب سفارشی را در نظر می‌گیرد و پردازش‌های اضافی را روی تبلیغاتی که یک پلتفرم فناوری تبلیغات به دستگاه برمی‌گرداند، انجام می‌دهد.

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

این راهنما نحوه کار با API مخاطب محافظت‌شده در اندروید را برای انجام موارد زیر شرح می‌دهد:

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

قبل از اینکه شروع کنی

قبل از شروع، موارد زیر را تکمیل کنید:

1. محیط توسعه خود را برای Privacy Sandbox در اندروید تنظیم کنید .
2. یا یک تصویر سیستم را روی یک دستگاه پشتیبانی‌شده نصب کنید یا یک شبیه‌ساز راه‌اندازی کنید که شامل پشتیبانی از Privacy Sandbox در اندروید باشد.

3. در یک ترمینال، با دستور adb زیر، دسترسی به API مخاطب محافظت‌شده (که به‌طور پیش‌فرض غیرفعال است) را فعال کنید .

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. در یک ترمینال، با استفاده از دستورات adb زیر، گزارش‌دهی بیکن را فعال کنید.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. مجوز ACCESS_ADSERVICES_CUSTOM_AUDIENCE را در مانیفست برنامه خود وارد کنید:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. به پیکربندی سرویس‌های تبلیغاتی در عنصر <application> مانیفست خود ارجاع دهید:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. منبع XML مربوط به سرویس‌های تبلیغاتی را که در مانیفست خود به آن ارجاع داده‌اید، مانند res/xml/ad_services_config.xml ، مشخص کنید. درباره مجوزهای سرویس‌های تبلیغاتی و کنترل دسترسی SDK بیشتر بدانید .

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. به طور پیش‌فرض، API انتخاب آگهی (Ad Selection API) محدودیت‌هایی را در حداکثر میزان حافظه‌ای که یک اسکریپت گزارش حراج یا نمایش می‌تواند اختصاص دهد، اعمال می‌کند. ویژگی محدودیت حافظه به نسخه WebView 105.0.5195.58 یا بالاتر نیاز دارد. این پلتفرم بررسی نسخه را اعمال می‌کند و در صورت عدم رضایت، فراخوانی‌های APIهای selectAds و reportImpression با شکست مواجه می‌شوند. دو گزینه برای تنظیم این مورد وجود دارد:

   • گزینه ۱: دستور adb زیر را برای غیرفعال کردن این بررسی اجرا کنید:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • گزینه ۲: نسخه بتای وب ویو را از فروشگاه گوگل پلی نصب کنید. این نسخه باید برابر یا بالاتر از نسخه‌ای باشد که قبلاً گفته شد.

به مخاطبان سفارشی بپیوندید

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

1. شیء CustomAudienceManager را مقداردهی اولیه کنید.
2. با مشخص کردن پارامترهای کلیدی مانند بسته خریدار و یک نام مرتبط، یک شیء CustomAudience ایجاد کنید. سپس، شیء JoinCustomAudienceRequest را با شیء CustomAudience مقداردهی اولیه کنید.
3. تابع joinCustomAudience() ناهمزمان را به همراه شیء JoinCustomAudienceRequest و اشیاء Executor و OutcomeReceiver مربوطه فراخوانی کنید.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

ترکیب پارامترهای زیر به طور منحصر به فرد هر شیء CustomAudience را در یک دستگاه مشخص می‌کند:

• owner : نام بسته‌ی برنامه‌ی مالک. این به طور ضمنی روی نام بسته‌ی برنامه‌ی فراخواننده تنظیم شده است.
• buyer : شناسه شبکه تبلیغاتی خریدار که تبلیغات را برای این مخاطب سفارشی مدیریت می‌کند.
• name : یک نام یا شناسه دلخواه برای مخاطب سفارشی.

فراخوانی مکرر تابع joinCustomAudience() با یک نمونه متفاوت از CustomAudience ، هر CustomAudience موجود را با پارامترهای owner, buyer و name منطبق به‌روزرسانی می‌کند. برای حفظ حریم خصوصی، نتیجه API بین "ایجاد" و "به‌روزرسانی" تمایزی قائل نمی‌شود.

علاوه بر این، CustomAudience باید با پارامترهای مورد نیاز زیر ایجاد شود:

• به‌روزرسانی روزانه URL : یک URL HTTPS که روزانه در پس‌زمینه جستجو می‌شود تا سیگنال‌های پیشنهاد قیمت کاربر، داده‌های پیشنهاد قیمت قابل اعتماد و URLها و فراداده‌های مربوط به تبلیغات را به‌روزرسانی کند.
• آدرس اینترنتی منطق پیشنهاد قیمت : یک آدرس اینترنتی HTTPS که هنگام انتخاب تبلیغ برای دریافت منطق پیشنهاد قیمت جاوا اسکریپت خریدار درخواست می‌شود. امضاهای تابع مورد نیاز را در این جاوا اسکریپت مشاهده کنید.
• شناسه‌های رندر تبلیغات : یک شناسه دلخواه که توسط تکنسین تبلیغات خریدار تنظیم می‌شود. این یک بهینه‌سازی برای تولید بار مفید برای B&A است.

پارامترهای اختیاری برای یک شیء CustomAudience می‌تواند شامل موارد زیر باشد:

• زمان فعال‌سازی : یک مخاطب سفارشی فقط می‌تواند پس از زمان فعال‌سازی در انتخاب تبلیغات و به‌روزرسانی‌های روزانه شرکت کند. این می‌تواند برای مثال برای جذب کاربران قدیمی یک برنامه مفید باشد.
• زمان انقضا : زمانی در آینده که پس از آن مخاطب سفارشی از دستگاه حذف می‌شود.
• سیگنال‌های پیشنهاد قیمت کاربر : یک رشته JSON حاوی سیگنال‌های کاربر، مانند زبان ترجیحی کاربر، که منطق پیشنهاد قیمت خریدار از آن استفاده می‌کند و جاوا اسکریپت برای تولید پیشنهادها در طول فرآیند انتخاب تبلیغ از آن استفاده می‌کند. این فرمت به پلتفرم‌های فناوری تبلیغات کمک می‌کند تا از کد در پلتفرم‌های مختلف استفاده مجدد کنند و مصرف در توابع جاوا اسکریپت را آسان‌تر می‌کند.
• داده‌های مناقصه‌ی معتبر : یک URL HTTPS و فهرستی از رشته‌های مورد استفاده در طول فرآیند انتخاب تبلیغ که سیگنال‌های مناقصه را از یک سرویس کلید/مقدار معتبر دریافت می‌کنند.
• تبلیغات : فهرستی از اشیاء AdData مربوط به تبلیغاتی که در انتخاب تبلیغ شرکت می‌کنند. هر شیء AdData شامل موارد زیر است:
  • Render URL : یک URL HTTPS که برای رندر تبلیغ نهایی درخواست می‌شود.
  • فراداده : یک شیء JSON که به صورت رشته‌ای سریالی شده و حاوی اطلاعاتی است که توسط منطق پیشنهاد قیمت خریدار در طول فرآیند انتخاب تبلیغ مصرف می‌شود.
  • فیلترهای تبلیغات : کلاسی که شامل تمام اطلاعات لازم برای فیلتر کردن تبلیغات نصب برنامه و محدود کردن دفعات نمایش در طول انتخاب تبلیغ است.

در اینجا مثالی از نمونه‌سازی شیء CustomAudience آورده شده است:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

مدیریت نتایج joinCustomAudio()

متد joinCustomAudience() ناهمزمان از شیء OutcomeReceiver برای ارسال نتیجه فراخوانی API استفاده می‌کند.

• تابع فراخوانی onResult() نشان می‌دهد که مخاطب سفارشی با موفقیت ایجاد یا به‌روزرسانی شده است.
• تابع فراخوانی onError() دو شرط ممکن را نشان می‌دهد.
  • اگر JoinCustomAudienceRequest با آرگومان‌های نامعتبر مقداردهی اولیه شود، AdServicesException یک IllegalArgumentException به عنوان علت نشان می‌دهد.
  • تمام خطاهای دیگر خطای AdServicesException با خطای IllegalStateException به عنوان علت دریافت می‌کنند.

در اینجا مثالی از مدیریت نتیجه‌ی joinCustomAudience() آورده شده است:

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

مخاطب سفارشی بگذارید

اگر کاربر دیگر معیارهای تجاری برای یک مخاطب سفارشی مشخص را برآورده نکند، یک برنامه یا SDK می‌تواند تابع leaveCustomAudience() را برای حذف مخاطب سفارشی از دستگاه فراخوانی کند. برای حذف یک CustomAudience بر اساس پارامترهای منحصر به فرد آن، موارد زیر را انجام دهید:

1. شیء CustomAudienceManager را مقداردهی اولیه کنید.
2. درخواست LeaveCustomAudienceRequest با buyer و name مخاطب سفارشی مقداردهی اولیه کنید. برای کسب اطلاعات بیشتر در مورد این فیلدهای ورودی، « به یک مخاطب سفارشی بپیوندید » را بخوانید.
3. متد leaveCustomAudience() ناهمزمان را با شیء LeaveCustomAudienceRequest و اشیاء Executor و OutcomeReceiver مربوطه فراخوانی کنید.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

مشابه فراخوانی joinCustomAudience() ، تابع OutcomeReceiver پایان فراخوانی API را اعلام می‌کند. برای کمک به حفظ حریم خصوصی، یک error result تفاوتی بین خطاهای داخلی و آرگومان‌های نامعتبر قائل نمی‌شود. تابع onResult() زمانی فراخوانی می‌شود که فراخوانی API به پایان رسیده باشد، چه مخاطب سفارشی منطبق با موفقیت حذف شده باشد و چه نشده باشد.

انتخاب تبلیغات را اجرا کنید

برای استفاده از API مخاطبان محافظت‌شده برای انتخاب تبلیغات، متد selectAds() را فراخوانی کنید:

1. یک شیء AdSelectionManager را مقداردهی اولیه کنید.
2. یک شیء AdSelectionConfig بسازید.
3. متد selectAds() غیرهمزمان را با شیء AdSelectionConfig و اشیاء Executor و OutcomeReceiver مربوطه فراخوانی کنید.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

متد selectAds() به یک ورودی AdSelectionConfig نیاز دارد که در آن باید پارامترهای مورد نیاز زیر را مشخص کنید:

• فروشنده : شناسه شبکه تبلیغاتی فروشنده که انتخاب تبلیغ را آغاز می‌کند.
• آدرس اینترنتی منطق تصمیم‌گیری : یک آدرس اینترنتی HTTPS که برای دریافت منطق جاوا اسکریپت شبکه تبلیغاتی فروشنده درخواست شده است.
  • آدرس اینترنتی HTTPS : برای دریافت منطق جاوا اسکریپت شبکه تبلیغاتی فروشنده، درخواست شده است. امضاهای تابع مورد نیاز را ببینید.
  • URI از پیش ساخته شده : که از فرمت انتخاب تبلیغات FLEDGE پیروی می‌کند. اگر یک uri از پیش ساخته شده پشتیبانی نشده یا ناقص ارسال شود، خطای IllegalArgumentException رخ می‌دهد.
• خریداران مخاطبان سفارشی : فهرست کاملی از شناسه‌های شبکه‌های تبلیغاتی خریدار که توسط فروشنده مجاز به شرکت در فرآیند انتخاب تبلیغ هستند. این شناسه‌های خریدار با CustomAudience.getBuyer() مخاطبان سفارشی شرکت‌کننده مطابقت دارند.

پارامترهای زیر را می‌توان به صورت اختیاری برای انتخاب تبلیغات سفارشی‌تر مشخص کرد:

• سیگنال‌های انتخاب آگهی : یک شیء JSON، که به صورت رشته سریالی شده است و حاوی سیگنال‌هایی است که توسط منطق پیشنهاد قیمت خریدار مصرف می‌شوند. جاوا اسکریپت از CustomAudience.getBiddingLogicUrl() واکشی شده است.
• سیگنال‌های فروشنده : یک شیء JSON، که به صورت رشته سریالی شده است و حاوی سیگنال‌هایی است که توسط منطق تصمیم‌گیری جاوا اسکریپتِ واکشی شده توسط فروشنده از AdSelectionConfig.getDecisionLogicUrl() مصرف می‌شوند.
• سیگنال‌های هر خریدار : نقشه‌ای از اشیاء JSON، که به صورت رشته سریالی شده‌اند، حاوی سیگنال‌هایی هستند که توسط منطق پیشنهاد قیمت خریداران خاص مصرف می‌شوند. جاوا اسکریپت از CustomAudience.getBiddingLogicUrl() واکشی شده است، که توسط فیلدهای خریدار مخاطبان سفارشی شرکت‌کننده شناسایی می‌شوند.
• تبلیغات زمینه‌ای: مجموعه‌ای از نامزدهای تبلیغاتی که مستقیماً از خریداران در طول حراجی که خارج از حراج مخاطبان محافظت‌شده برگزار می‌شود، جمع‌آوری می‌شوند.

پس از انتخاب یک تبلیغ، نتایج، پیشنهادات و سیگنال‌ها به صورت داخلی برای گزارش‌گیری ذخیره می‌شوند. تابع فراخوانی OutcomeReceiver.onResult() یک AdSelectionOutcome برمی‌گرداند که شامل موارد زیر است:

• یک URL رندر برای تبلیغ برنده، که از AdData.getRenderUrl() به دست آمده است.
• یک شناسه انتخاب تبلیغ منحصر به فرد برای کاربر دستگاه. این شناسه برای گزارش نمایش تبلیغ استفاده می‌شود.

اگر انتخاب تبلیغ به دلایلی مانند آرگومان‌های نامعتبر، وقفه‌های زمانی یا مصرف بیش از حد منابع با موفقیت انجام نشود، تابع فراخوانی OutcomeReceiver.onError() یک AdServicesException با رفتارهای زیر ایجاد می‌کند:

• اگر انتخاب تبلیغ با آرگومان‌های نامعتبر آغاز شود، AdServicesException یک IllegalArgumentException به عنوان علت نشان می‌دهد.
• تمام خطاهای دیگر خطای AdServicesException با خطای IllegalStateException به عنوان علت دریافت می‌کنند.

تبلیغات متنی

مخاطب محافظت‌شده می‌تواند تبلیغات متنی را در یک حراج محافظت‌شده بگنجاند. تبلیغات متنی باید در سرور فناوری تبلیغات انتخاب شده و خارج از APIهای مخاطب محافظت‌شده به دستگاه بازگردانده شوند. سپس می‌توان تبلیغات متنی را با استفاده از AdSelectionConfig در حراج گنجاند که در آن نقطه، عملکردی مشابه تبلیغات روی دستگاه دارند، از جمله واجد شرایط بودن برای فیلتر کردن تبلیغات منفی. پس از اتمام حراج مخاطب محافظت‌شده، باید تابع reportImpression() را فراخوانی کنید. این تابع reportWin() را در تبلیغ متنی برنده، مطابق با الگوی گزارش نمایش ، فراخوانی می‌کند تا تبلیغ برنده را در یک دستگاه دریافت کند. هر تبلیغ متنی به یک خریدار، یک پیشنهاد قیمت، یک لینک به منطق گزارش، یک URL رندر و ابرداده تبلیغ نیاز دارد.

برای استقرار تبلیغات متنی در برنامه، برنامه هدف باید یک شیء ContextualAds ایجاد کند:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

شیء ContextualAds حاصل می‌تواند هنگام ایجاد AdSelectionConfig شما ارسال شود:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

فیلتر کردن تبلیغات نصب برنامه

فیلتر کردن تبلیغات نصب برنامه به شما کمک می‌کند تا تبلیغات نصب برنامه‌هایی را که از قبل روی دستگاه نصب شده‌اند، فیلتر کنید.

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

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

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

مرحله بعدی، تنظیم فیلترینگ تبلیغات در داخل برنامه ناشر است. طرفی که تبلیغ را در داخل برنامه ناشر ارائه می‌دهد (به احتمال زیاد یک SDK سمت عرضه است) باید شیء AdFilters خود را با اطلاعاتی در مورد اینکه کدام تبلیغات مربوط به برنامه‌هایی است که می‌خواهند فیلتر کنند، مقداردهی اولیه کند:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

ناشران سمت تقاضا همچنین ممکن است برای تبلیغاتی که در مخاطبان سفارشی آنها وجود دارد، یک AdFilter تنظیم کنند.

AdFilters همچنین می‌توانند در زمان نمونه‌سازی یک شیء AdData جدید ارسال شوند:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

فیلترینگ سقف فرکانس

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

دو جزء اصلی در یک فیلتر سقف فرکانس وجود دارد: نوع رویداد تبلیغ و کلید شمارنده تبلیغ. انواع رویدادهای تبلیغ موجود که می‌توانند مورد استفاده قرار گیرند عبارتند از:

• برد : رویداد برد نشان می‌دهد که تبلیغ در یک مزایده برنده شده است. رویدادهای برد به طور خودکار توسط API مخاطبان محافظت‌شده به‌روزرسانی می‌شوند و توسعه‌دهنده نمی‌تواند مستقیماً آنها را فراخوانی کند. داده‌های برد فقط برای تبلیغات درون یک مخاطب سفارشی مشخص قابل مشاهده است.
• نمایش : جدا از reportImpression ، یک فراخوانی‌کننده‌ی روی دستگاه (SSP یا MMP) از updateAdCounterHistogram() برای فراخوانی رویدادهای نمایش در نقطه‌ای از کد که انتخاب می‌کنند، استفاده می‌کند. رویدادهای نمایش برای همه تبلیغات متعلق به یک DSP مشخص قابل مشاهده هستند و محدود به تبلیغات در همان مخاطب سفارشی نیستند.
• مشاهده : رویداد توسط فراخوانی‌کننده‌ی روی دستگاه (SSP یا MMP) در نقطه‌ای از کد که با استفاده از فراخوانی updateAdCounterHistogram() انتخاب می‌کنند، فراخوانی می‌شود. رویدادهای مشاهده برای همه تبلیغات متعلق به یک DSP مشخص قابل مشاهده هستند و محدود به تبلیغات در همان مخاطب سفارشی نیستند.
• کلیک : رویداد توسط فراخوانی‌کننده‌ی روی دستگاه (SSP یا MMP) در نقطه‌ای از کد که با استفاده از فراخوانی updateAdCounterHistogram() انتخاب می‌کنند، فراخوانی می‌شود. رویدادهای کلیک برای همه تبلیغات متعلق به یک DSP مشخص قابل مشاهده هستند و محدود به تبلیغات در همان مخاطب سفارشی نیستند.

در برنامه ناشر، یک SSP یا MMP که در دستگاه حضور دارد، رویدادهای تبلیغاتی را فراخوانی می‌کند. هنگامی که updateAdCounterHistogram() فراخوانی می‌شود، شمارنده فیلتر محدودیت فرکانس افزایش می‌یابد تا حراج‌های آینده اطلاعات به‌روزی در مورد میزان مواجهه کاربر با یک تبلیغ مشخص داشته باشند. انواع رویدادهای تبلیغاتی به طور اجباری به اقدام کاربر مربوطه وابسته نیستند و دستورالعمل‌هایی هستند که برای کمک به تماس‌گیرندگان در ساختار سیستم رویداد خود ارائه می‌شوند. برای افزایش شمارنده‌های تبلیغات در زمان یک رویداد، عامل روی دستگاه، شناسه انتخاب تبلیغ حراج تبلیغاتی برنده را ارائه می‌دهد.

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

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

برای استفاده از محدودیت فرکانس در حراج خود، ابتدا باید اشیاء KeyedFrequencyCap را ایجاد کنید:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

پس از ایجاد اشیاء KeyedFrequencyCap ، می‌توانید آنها را به یک شیء AdFilters ارسال کنید.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

وقتی شیء AdFilters با فیلترهای محدودیت فرکانس پر می‌شود، می‌تواند هنگام ایجاد مخاطب سفارشی ارسال شود:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

وقتی فیلترهای محدودیت فرکانس در یک مخاطب سفارشی پیاده‌سازی می‌شوند، SSP می‌تواند رویدادهای کلیک، مشاهده یا نمایش لازم را فراخوانی کند.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

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

فیلتر کردن تبلیغات متنی بدون تماس‌های شبکه

اگر هیچ تقاضای بازاریابی مجددی در دستگاه وجود نداشته باشد، می‌توانید انتخاب تبلیغ را برای تبلیغات متنی بدون فراخوانی شبکه اجرا کنید. با URI های از پیش ساخته شده و لیستی از تبلیغات متنی با پیشنهادات، پلتفرم می‌تواند از بازیابی منطق پیشنهاد، سیگنال‌های پیشنهاد و سیگنال‌های امتیازدهی صرف نظر کند. این پلتفرم از یک URI از پیش ساخته شده برای انتخاب تبلیغ متنی با بالاترین پیشنهاد استفاده می‌کند.

برای بهبود تأخیر، تکنسین‌های تبلیغات می‌توانند یک جریان انتخاب تبلیغ را اجرا کنند که فقط شامل تبلیغات متنی با قابلیت فیلتر کردن تبلیغ بدون فراخوانی‌های شبکه باشد. این امر با استفاده از URI های از پیش ساخته شده برای امتیازدهی سیگنال‌ها محقق می‌شود. برای مشاهده لیستی از پیاده‌سازی‌های scoreAds به بخش موارد استفاده و نام‌های URI از پیش ساخته شده پشتیبانی شده مراجعه کنید.

برای اجرای انتخاب تبلیغات بدون تماس‌های شبکه:

1. فیلتر کردن تبلیغات را تنظیم کنید
2. تبلیغات متنی خود را ایجاد کنید

3. یک شیء AdSelectionConfig با موارد زیر ایجاد کنید:

   1. فهرست خالی خریداران
   2. یک URI از پیش ساخته شده برای انتخاب بالاترین پیشنهاد
   3. تبلیغات متنی
   4. یک URI خالی برای سیگنال‌های امتیازدهی. URI خالی مجاز است نشان دهد که شما نمی‌خواهید از واکشی سیگنال‌های مورد اعتماد برای امتیازدهی استفاده کنید:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. انتخاب تبلیغ را اجرا کنید:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

هنگام استفاده از URI های از پیش ساخته شده، جاوا اسکریپت گزارش خود را اجرا کنید

امروزه، پلتفرم Privacy Sandbox فقط یک پیاده‌سازی اولیه‌ی گزارش‌دهی جاوااسکریپت برای URIهای از پیش ساخته شده دارد. اگر می‌خواهید جاوااسکریپت گزارش‌دهی خودتان را اجرا کنید و در عین حال از URIهای از پیش ساخته شده برای انتخاب تبلیغات با تأخیر کم استفاده کنید، می‌توانید DecisionLogicUri را بین انتخاب تبلیغات و اجرای گزارش‌دهی نادیده بگیرید.

1. مراحلی را برای اجرای انتخاب تبلیغ برای تبلیغات متنی با استفاده از URI های از پیش ساخته شده اجرا کنید

2. قبل از اجرای گزارش، یک کپی از AdSelectionConfig خود ایجاد کنید

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. گزارش نمایش را اجرا کنید

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

اجرای میانجیگری آبشاری

میانجیگری آبشاری نیازمند چندین SDK شخص ثالث (شبکه‌های 3P) است که توسط یک شبکه میانجیگری SDK شخص ثالث هماهنگ شوند. میانجیگری آبشاری صرف نظر از اینکه حراج روی دستگاه انجام شده باشد یا روی سرویس‌های مناقصه و مزایده (B&A) اجرا شده باشد، به یک شکل انجام می‌شود.

شبکه‌های ۳P

شبکه‌های 3P باید آداپتوری ارائه دهند که به شبکه میانجی اجازه دهد روش‌های لازم برای اجرای حراج را فراخوانی کند:

• انتخاب تبلیغات را اجرا کنید
• گزارش برداشت‌ها

در اینجا مثالی از یک آداپتور شبکه میانجیگری آورده شده است:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

هر SDK مدیران و مشتریان خدمات انتخاب تبلیغات خود و پیاده‌سازی selectAds و reportImpressions مخصوص به خود را دارد. ارائه‌دهندگان SDK می‌توانند به بخش‌های مربوط به نحوه اجرای انتخاب تبلیغات برای حراج‌های روی دستگاه یا توضیح B&A برای حراج‌های B&A مراجعه کنند. برای گزارش، نحوه گزارش نمایش تبلیغات را دنبال کنید (پس از گزارش نمایش SSP واحد ).

شبکه میانجیگری

مشابه شبکه‌های 3P، شبکه‌های میانجیگری به پیاده‌سازی selectAds و reportImpression نیاز دارند. برای اطلاعات بیشتر به بخش‌های نحوه‌ی اجرای انتخاب تبلیغ و نحوه‌ی گزارش تعداد نمایش تبلیغ مراجعه کنید.

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

بازیابی زنجیره میانجیگری و کف قیمت‌ها

شبکه میانجیگری مسئول بازیابی تبلیغات زمینه‌ای طرف اول (1P)، زنجیره میانجیگری و کف‌های پیشنهاد شبکه‌های شخص ثالث (3P) است. این امر می‌تواند در درخواست بازیابی تبلیغات زمینه‌ای اجرا شده توسط شبکه میانجیگری اتفاق بیفتد. زنجیره میانجیگری نحوه تکرار از طریق شبکه‌های 3P را تعیین می‌کند و کف‌های پیشنهاد می‌توانند به عنوان adSelectionSignals به فرآیند حراج منتقل شوند.

قرارگیری شبکه در زنجیره میانجیگری

یک SDK میانجی‌گری می‌تواند بر اساس eCPM زنده‌ی پیشنهادهای تبلیغاتی 1P خود، خود را در زنجیره میانجی‌گری قرار دهد. در API مخاطب محافظت‌شده، پیشنهادهای تبلیغاتی مبهم هستند. یک SDK میانجی‌گری باید از AdSelectionFromOutcomesConfig استفاده کند تا بتواند پیشنهاد یک تبلیغ 1P مشخص را با کف پیشنهاد شبکه 3P بعدی در زنجیره مقایسه کند. اگر پیشنهاد 1P بالاتر از کف پیشنهاد باشد، به این معنی است که SDK میانجی‌گری در مقابل آن شبکه 3P قرار گرفته است.

انتخاب تبلیغات را اجرا کنید

برای بازیابی یک کاندید تبلیغ ۱P، شبکه میانجیگری می‌تواند یک مزایده روی دستگاه را طبق مراحل موجود در بخش انتخاب تبلیغ اجرا کند. این کار یک کاندید تبلیغ ۱P، یک پیشنهاد قیمت و یک AdSelectionId ایجاد می‌کند که در فرآیند میانجیگری استفاده می‌شود.

ایجاد یک AdSelectionFromOutcomesConfig

یک AdSelectionFromOutcomesConfig به شبکه میانجیگری اجازه می‌دهد تا لیستی از AdSelectionIds (نتایج مزایده‌های قبلی)، سیگنال‌های انتخاب تبلیغ و یک URI برای دریافت جاوا اسکریپت که یک تبلیغ را از بین چندین کاندید انتخاب می‌کند، ارسال کند. لیست AdSelectionIds به همراه پیشنهادات و سیگنال‌های آنها به جاوا اسکریپت ارسال می‌شود که می‌تواند در صورت عبور از کف پیشنهاد، یکی از AdSelectionIds را برگرداند، یا در صورت ادامه زنجیره میانجیگری، هیچ کدام را برنگرداند.

شبکه‌های میانجیگری با استفاده از AdSelectionId مربوط به 1P از بخش قبل و کف قیمت پیشنهادی برای شبکه 3P که در نظر گرفته شده است، یک AdSelectionFromOutcomesConfig ایجاد می‌کنند. برای هر مرحله در زنجیره میانجیگری، باید یک AdSelectionFromOutcomesConfig جدید ایجاد شود.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

لغو متد selectAds() برای میانجیگری آبشاری نیاز به ورودی AdSelectionFromOutcomesConfig دارد که در آن باید پارامترهای مورد نیاز زیر را مشخص کنید:

• فروشنده : شناسه شبکه تبلیغاتی فروشنده که انتخاب تبلیغ را آغاز می‌کند.
• AdSelectionIds : یک لیست تک‌تایی از اجرای قبلی selectAds() برای یک تبلیغ تک‌صفحه‌ای.
• سیگنال‌های انتخاب آگهی : یک شیء JSON، که به صورت رشته سریالی شده است و حاوی سیگنال‌هایی است که توسط منطق پیشنهاد قیمت خریدار استفاده می‌شوند. در این مورد، کف قیمت بازیابی شده برای شبکه 3P داده شده را نیز شامل می‌شود.
• URI منطق انتخاب : یک URL HTTPS که در طول انتخاب تبلیغ برای دریافت جاوا اسکریپت شبکه میانجیگری جهت انتخاب یک تبلیغ برنده، پرس و جو می‌شود. امضاهای تابع مورد نیاز را در این جاوا اسکریپت مشاهده کنید. جاوا اسکریپت باید در صورت بالاتر بودن قیمت پیشنهادی از کف قیمت، تبلیغ 3P را برگرداند، در غیر این صورت null برگرداند. این به SDK میانجیگری اجازه می‌دهد تا زنجیره میانجیگری را هنگام یافتن برنده کوتاه کند.

پس از ایجاد AdSelectionOutcomesConfig ، متد selectAds() را از شبکه 3P که در ابتدا در زنجیره قرار دارد، فراخوانی کنید.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

میانجیگری آبشاری را هماهنگ کنید

ترتیب عملیات برای اجرای فرآیند میانجیگری به شرح زیر است.

1. انتخاب تبلیغات ۱P را اجرا کنید.
2. در طول زنجیره میانجیگری تکرار کنید. برای هر شبکه 3P، موارد زیر را انجام دهید:
   1. پیکربندی AdSelectionFromOutcomeConfig را شامل شناسه outcomeId ۱P و حداقل قیمت پیشنهادی کیت توسعه نرم‌افزار ۳P بسازید.
   2. تابع selectAds() را با پیکربندی مرحله قبل فراخوانی کنید.
   3. اگر نتیجه خالی نبود، تبلیغ را برگردانید.
   4. متد selectAds() آداپتور شبکه SDK فعلی را فراخوانی کنید. اگر نتیجه خالی نبود، تبلیغ را برگردانید.
3. اگر هیچ برنده‌ای از زنجیره پیدا نشد، آگهی ۱P را برگردانید.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

گزارش نمایش تبلیغات

بسته به نحوه اجرای حراج، دو جریان برای گزارش نمایش آگهی وجود دارد. اگر شما یک SSP هستید که حراج را اجرا می‌کند، این بخش را دنبال کنید. اگر می‌خواهید میانجیگری آبشاری را پیاده‌سازی کنید، مراحل موجود در بخش گزارش نمایش میانجیگری آبشاری را دنبال کنید.

گزارش برداشت SSP واحد

پس از اینکه یک تبلیغ برنده از گردش کار انتخاب تبلیغ انتخاب شد، می‌توانید با استفاده از متد AdSelectionManager.reportImpression() میزان نمایش را به پلتفرم‌های طرف خرید و طرف فروش شرکت‌کننده گزارش دهید. برای گزارش نمایش تبلیغ:

1. یک شیء AdSelectionManager را مقداردهی اولیه کنید.
2. یک شیء ReportImpressionRequest با شناسه انتخاب تبلیغ بسازید.
3. متد reportImpression() ناهمزمان را با شیء ReportImpressionRequest و اشیاء Executor و OutcomeReceiver مربوطه فراخوانی کنید.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

مقداردهی اولیه ReportImpressionRequest با پارامترهای مورد نیاز زیر:

• شناسه انتخاب تبلیغ : شناسه‌ای منحصر به فرد که فقط برای کاربر دستگاه منحصر به فرد است و انتخاب موفقیت‌آمیز تبلیغ را مشخص می‌کند.
• پیکربندی انتخاب تبلیغ : همان پیکربندی مورد استفاده در فراخوانی selectAds() که با شناسه انتخاب تبلیغ ارائه شده مشخص می‌شود.

متد reportImpression() ناهمزمان از شیء OutcomeReceiver برای ارسال نتیجه فراخوانی API استفاده می‌کند.

• تابع فراخوانی onResult() نشان می‌دهد که آیا URLهای گزارش‌دهنده‌ی نمایش ایجاد شده‌اند و آیا درخواست زمان‌بندی شده است یا خیر.
• تابع فراخوانی onError() شرایط احتمالی زیر را نشان می‌دهد:
  • اگر فراخوانی با یک آرگومان ورودی نامعتبر آغاز شود، AdServicesException یک IllegalArgumentException به عنوان علت نشان می‌دهد.
  • تمام خطاهای دیگر خطای AdServicesException با خطای IllegalStateException به عنوان علت دریافت می‌کنند.

گزارش‌دهی برداشت با میانجیگری آبشاری

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

ارائه‌دهندگان خدمات یکپارچه (SSP) می‌توانند از این نمونه کد 3P SDK به عنوان نمونه اولیه برای نحوه پیوستن به جریان‌های میانجیگری استفاده کنند:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

نقاط پایانی گزارش نمایش

رابط برنامه‌نویسی کاربردی (API) مربوط به گزارش، درخواست‌های HTTPS GET را به نقاط انتهایی ارائه شده توسط پلتفرم سمت فروش و پلتفرم سمت خرید برنده صادر می‌کند:

نقطه پایانی پلتفرم خرید:

• این API از URL منطق پیشنهاد قیمت مشخص شده در مخاطب سفارشی برای دریافت جاوا اسکریپت ارائه شده توسط خریدار که شامل منطق بازگرداندن URL گزارش نمایش است، استفاده می‌کند.
• تابع جاوا اسکریپت reportWin() را فراخوانی کنید، که انتظار می‌رود URL گزارش تعداد بازدیدهای خریدار را برگرداند.

نقطه پایانی پلتفرم سمت فروش:

• از آدرس اینترنتی منطق تصمیم که در شیء AdSelectionConfig مشخص شده است، برای دریافت جاوا اسکریپت منطق تصمیم فروشنده استفاده کنید.
• تابع جاوا اسکریپت reportResult() فراخوانی کنید، که انتظار می‌رود URL گزارش تعداد نمایش فروشنده را برگرداند.

گزارش خدمات مناقصه و مزایده

حراجی که در سرویس‌های Bidding & Auction اجرا می‌شود، تمام اطلاعات گزارش‌دهی لازم، از جمله URLهای تولید شده برای گزارش تعامل تبلیغاتی ، را در پاسخ رمزگذاری شده از حراج سمت سرور خواهد داشت. هنگامی که پاسخ رمزگشایی می‌شود، URLهای مناسب در پلتفرم ثبت می‌شوند، بنابراین گزارش تبلیغات و نمایش از همان مراحل پیروی می‌کند.

گزارش‌دهی بهترین تلاش برای نمایش نتایج

متد reportImpression() به گونه‌ای طراحی شده است که تکمیل گزارش‌گیری را با بهترین تلاش ارائه دهد.

گزارش تعاملات تبلیغاتی

مخاطب محافظت‌شده (Protected Audience) پشتیبانی لازم برای گزارش تعاملات جزئی‌تر برای یک تبلیغ رندر شده را فراهم می‌کند. این می‌تواند شامل تعاملاتی مانند زمان مشاهده، کلیک‌ها، هاورها یا هر معیار مفید دیگری باشد که قابل جمع‌آوری باشد. فرآیند دریافت این گزارش‌ها به دو مرحله نیاز دارد. ابتدا، خریداران و فروشندگان باید برای دریافت این گزارش‌ها در جاوا اسکریپت گزارش‌دهی خود ثبت‌نام کنند. سپس، مشتری باید این رویدادها را گزارش دهد.

ثبت نام برای دریافت رویدادهای تعاملی

ثبت نام برای رویدادهای تعاملی در توابع جاوا اسکریپت reportWin() خریدار و reportResult() فروشنده با استفاده از یک تابع جاوا اسکریپت ارائه شده توسط پلتفرم: registerAdBeacon انجام می‌شود. برای ثبت نام برای دریافت گزارش رویداد، تابع جاوا اسکریپت پلتفرم را از جاوا اسکریپت گزارش خود فراخوانی کنید. قطعه کد زیر از reportWin() خریدار استفاده می‌کند، اما همین رویکرد برای reportResult() نیز اعمال می‌شود.

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

گزارش رویدادهای تعاملی

پس از گزارش یک نمایش، مشتریان می‌توانند با استفاده از متد AdSelectionManager.reportInteraction() تعاملات را به پلتفرم‌های برنده‌ی خرید و فروش که قبلاً ثبت شده‌اند، گزارش دهند. برای گزارش یک رویداد تبلیغاتی:

1. یک شیء AdSelectionManager را مقداردهی اولیه کنید.
2. یک شیء ReportInteractionRequest با شناسه انتخاب تبلیغ، کلید تعامل، داده‌های تعامل و مقصد گزارش بسازید.
3. متد reportInteraction() ناهمزمان را با شیء request و اشیاء مربوطه Executor و OutcomeReceiver فراخوانی کنید.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

مقداردهی اولیه ReportInteractionRequest با پارامترهای مورد نیاز زیر:

• شناسه انتخاب تبلیغ : شناسه انتخاب تبلیغی که از AdSelectionOutcome قبلاً بازگردانده شده بازیابی شده است.
• کلید تعامل : یک کلید رشته‌ای که توسط کلاینت تعریف می‌شود و اقدام گزارش‌شده را توصیف می‌کند. این کلید باید با کلیدی که توسط فروشنده یا خریدار در توابع گزارش‌دهی جاوا اسکریپت ثبت شده است، مطابقت داشته باشد.
• داده‌های تعاملی : رشته‌ای حاوی داده‌هایی که باید در گزارش رویداد گنجانده شوند و به سرورهای گزارش‌دهنده ارسال شوند.
• گزارش‌دهی به مقصدها : یک ماسک بیتی که مشخص می‌کند رویدادها باید به خریدار، فروشنده یا هر دو گزارش شوند. این پرچم‌ها توسط پلتفرم ارائه می‌شوند و ماسک مقصد نهایی را می‌توان با استفاده از عملیات بیتی ایجاد کرد. برای گزارش به یک مقصد، می‌توانید مستقیماً از پرچمی که توسط پلتفرم ارائه شده است استفاده کنید. برای گزارش به چندین مقصد، می‌توانید از عملگر بیتی OR ( | ) برای ترکیب مقادیر پرچم استفاده کنید.

متد reportInteraction() ناهمزمان از شیء OutcomeReceiver برای ارسال نتیجه فراخوانی API استفاده می‌کند.

• تابع فراخوانی onResult() نشان می‌دهد که فراخوانی تعامل گزارش معتبر است.
• تابع فراخوانی onError() شرایط احتمالی زیر را نشان می‌دهد:
  • اگر فراخوانی زمانی انجام شود که برنامه در پس‌زمینه در حال اجرا باشد، یک IllegalStateException با توضیحی از علت خطا بازگردانده می‌شود.
  • اگر کلاینت از فراخوانی reportInteraction() منع شده باشد، خطای LimitExceededException برگردانده می‌شود.
  • اگر پکیج برای فراخوانی APIهای حفظ حریم خصوصی ثبت نشده باشد، یک SecurityException() برگردانده می‌شود.
  • اگر برنامه‌ای که تعاملات را گزارش می‌دهد با برنامه‌ای که selectAds() را فراخوانی کرده است متفاوت باشد، یک IllegalStateException برگردانده می‌شود.
• اگر کاربر به فعال کردن APIهای Privacy Sandbox رضایت نداده باشد، تماس بی‌صدا قطع خواهد شد.

نقاط پایانی گزارش تعامل

The report interaction API issues HTTPS POST requests to endpoints provided by the sell-side platform and the winning buy-side platform. Protected Audience will match the interaction keys with the URIs declared in reporting JavaScript and issue a POST request to each endpoint for each interaction being reported. The Content-Type of the request is plain text with the body being the Interaction Data.

Best effort Interaction reporting

The reportInteraction() is designed to offer a best-effort completion of reporting through HTTP POST.

Daily background update

When creating a custom audience, your app or SDK can initialize custom audience metadata. Additionally, the platform can update the following pieces of custom audience metadata with a daily background update process.

• User bidding signals
• Trusted bidding data
• AdData list

This process queries against the Daily update URL defined in the custom audience and the URL may return a JSON response.

• The JSON response may contain any of the supported metadata fields that needs to be updated.
• Each JSON field is validated independently. The client ignores any malformed fields which results in no updates to that particular field in the response.
• An empty HTTP response or an empty JSON object " {} " results in no metadata updates.
• The response message size must be limited to 10 KB.
• All URIs are required to use HTTPS.
• trusted_bidding_uri must share the same ETLD+1 as the buyer.

Example: JSON response for background daily update

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript for ad selection

The ad selection workflow orchestrates the execution of buyer-provided and seller-provided JavaScript.

Buyer-provided JavaScript is fetched from the Bidding logic URL specified in the custom audience. The returned JavaScript should include the following functions:

• generateBid()
• reportWin()

Seller-provided JavaScript is fetched from the decision logic URL specified in the AdSelectionConfig parameter for the ad selection API. The returned JavaScript should include the following functions:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Input parameters:

• ad : a JSON object with the format var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals : JSON objects specified in the auction configuration object

• custom_audience_bidding_signals : JSON object generated by the platform. The format for this JSON object is:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  کجا:

  • owner , buyer , and name are string taken from the properties with the same name of the Custom Audience participating to the ad selection
  • activation_time and expiration_time are the time of activation and expiration of the custom audience, expressed as seconds since the Unix epoch
  • ca_user_bidding_signals is a JSON string specified in the userBiddingSignals field of the CustomAudience at creation time
  • trusted_bidding_signals, contextual_signals , and user_signals are JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

نتیجه:

• ad : is the ad the bid refers to. The script is allowed to return a copy of the ad it received with different metadata. The render_url property of the ad is expected to be unaltered.
• bid : a float value representing the bid value for this ad
• status : an integer value that can be:
  • 0 : for a successful execution
  • 1 : (or any non-zero value) in case any of the input signals is invalid. In case a non-zero value is returned by generate-bid the bidding process is invalidated for all the CA ads

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Input parameters:

• ad : see the generateBid documentation
• bid : the bid value for the ad

• ad_selection_config : a JSON object representing the AdSelectionConfig parameter of the selectAds API. The format is:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals : JSON objects read from the sellerSignals AdSelectionConfig API parameter

• trusted_scoring_signal : read from the adSelectionSignals field in the AdSelectionConfig API parameter

• contextual_signals, user_signals : JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

• per_buyer_signals : JSON object read from the perBuyerSignal map in the AdSelectionConfig API parameter using as key the current Custom Audience buyer. Empty if the map doesn't contain any entry for the given buyer.

خروجی:

• score : a float value representing the score value for this ad
• status : an integer value that can be:
  • 0: for a successful execution
  • 1: in case the customAudienceSignals are invalid
  • 2: in case the AdSelectionConfig is invalid
  • 3: in case any of the other signals is invalid
  • Any non-zero value causes the failure of the process, the value determines the type of exception thrown

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Input parameters:

• outcomes : a JSON object {"id": id_string, "bid": bid_double}
• selection_signals : JSON objects specified in the auction configuration object

خروجی:

• status : 0 for success, non-zero for failure
• result : one of the outcomes passed in or null

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 }
   };
}

Input parameters:

• ad_selection_config : see the documentation of scoreAds
• render_url : the render URL of the winning ad
• bid : the bid offered for the winning ad
• contextual_signals : see the documentation of generateBid

خروجی:

• status: 0 for success and non-zero for failure
• results : a JSON objects containing:
  • signals_for_buyer : a JSON object that is passed to the reportWin function
  • reporting_url : a URL that is used by the platform to notify the impression to the buyer

reportWin()

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

Input parameters:

• ad_selection_signals, per_buyer_signals : see the documentation for scoreAd
• signals_for_buyer : a JSON object returned by reportResult
• contextual_signals, custom_audience_signals : see the documentation for generateBid

خروجی:

• status: 0 for success and non-zero for failure
• results : a JSON object containing:
  • reporting_url : a URL that is used by the platform to notify the impression to the seller

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Input Parameters :

• beacons : An object containing key-value pairs of interaction keys and reporting URIs. The format is:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key : A string representing the event. This is used by the platform later when reporting event interactions to look up the reporting_uri that should be notified. This key needs to match between what the buyer or seller is registering, and what the seller is reporting.
  • reporting_uri : A URI to receive event reports. This should be specific to the event type being reported. It must accept a POST request to handle any data reported along with the event.

  برای مثال:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

Ad Selection prebuilt URIs

Prebuilt URIs give ad techs the ability to appoint JavaScript functions for ad selection decision logic in the AdSelectionConfig and AdSelectionFromOutcomesConfig classes. Prebuilt URIs don't require network calls to download the corresponding JavaScript. Ad techs can use prebuilt URIs without having to set up an enrolled domain to host the JavaScript.

A prebuilt URI is constructed using the following format:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

The Privacy Sandbox platform provides JavaScript using the information from this URI in the runtime.

An IllegalArgumentException is thrown if:

• any of the required parameters are not present in the URI
• there are unrecognized parameters in the URI

Supported prebuilt URI use cases and names

Use case 1: ad-selection

Prebuilt URIs under the ad-selection use case are supported in the selectAds(AdSelectionConfig) flow.

Prebuilt URI name: highest-bid-wins

This prebuilt URI provides a JavaScript that picks the ad with the highest bid after bidding. It also provides a basic reporting function to report the winner's render_uri and bid .

Required parameters

reportingUrl : The base reporting URL that is parameterized with the render_uri and the bid of the winning ad:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

کاربرد

If your base reporting URL is https://www.ssp.com/reporting then the prebuilt URI would be:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Use case 2: ad-selection-from-outcomes

Prebuilt URIs under the ad-selection-from-outcomes use case support the selectAds(AdSelectionFromOutcomesConfig) workflow.

Prebuilt URI name: waterfall-mediation-truncation

The waterfall-mediation-truncation prebuilt URI provides JavaScript that implements waterfall mediation truncation logic where the JavaScript returns a first-party ad if the bid is higher then or equal to the bid floor , and otherwise returns null .

Required parameters

bidFloor : The key of the bid floor value passed in the getSelectionSignals() that is compared against the mediation SDK's ad.

کاربرد

If your ad selection signals look like {"bid_floor": 10} then the resulting prebuilt URI would be:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

آزمایش

To help you get started with the Protected Audience API, we've created sample apps in Kotlin and Java, which can be found on GitHub .

پیش‌نیازها

The Protected Audience API requires some JavaScript during ad selection and impression reporting. There are two methods of providing this JavaScript in a testing environment:

• Run a server with the required HTTPS endpoints that returns the JavaScript
• Override remote fetching by providing the necessary code from a local source

Either approach requires setting up an HTTPS endpoint to handle impression reporting.

HTTPS endpoints

To test ad selection and impression reporting, you need to set up 7 HTTPS endpoints that your test device or emulator can access:

1. Buyer endpoint that serves the bidding logic JavaScript.
2. An endpoint that serves the bidding signals.
3. Seller endpoint that serves the decision logic JavaScript.
4. An endpoint that serves scoring signals.
5. Winning buyer impression reporting endpoint.
6. Seller impression reporting endpoint.
7. An endpoint to serve the daily updates for a custom audience.

For convenience, the GitHub repository provides basic JavaScript code for testing purposes. It also includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

Override remote fetching of JavaScript

This feature is intended to be used for end-to-end testing. To override remote fetching, your app must run in debug mode with developer options enabled.

To enable debug mode for your application, add the following line to the application attribute in your AndroidManifest.xml:

<application
  android:debuggable="true">

For an example of how to use these overrides, see the the Protected Audience API sample app on GitHub.

You need to add your own custom JavaScript to handle ad selection routines such as bidding, scoring decisions, and reporting. You can find basic JavaScript code examples that handle all required requests in the GitHub repo . The Protected Audience API sample application demonstrates how to read code from that file and prepare it for use as an override.

It is possible to override sell-side and buy-side JavaScript fetching independently, though you need an HTTPS endpoint to serve any JavaScript you aren't providing overrides for. See the README for information about how to set up a server that handles these cases.

It is only possible to override JavaScript fetching for custom audiences that are owned by your package.

Override sell-side JavaScript

To set up an override of sell-side JavaScript, do the following as demonstrated in the following code example:

1. Initialize an AdSelectionManager object.
2. Get a reference to TestAdSelectionManager from the AdSelectionManager object.
3. Build an AdSelectionConfig object.
4. Build an AddAdSelectionOverrideRequest with the AdSelectionConfig object and a String representing the JavaScript you intend to use as an override.
5. Call the asynchronous overrideAdSelectionConfigRemoteInfo() method with the AddAdSelectionOverrideRequest object and relevant Executor and OutcomeReceiver objects.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

See the Run ad selection section for more information about what each of the fields in the AdSelectionConfig represent. The key difference is that the decisionLogicUrl can be set to a placeholder value as it will be ignored.

In order to override the JavaScript used during ad selection, the decisionLogicJs must contain the proper seller-side function signatures . For an example of how to read a JavaScript file as a string, see the Protected Audience API sample app on GitHub.

The asynchronous overrideAdSelectionConfigRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Future calls to selectAds() will use whatever decision and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions:

• If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
• If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset sell-side overrides

This section assumes that you have overridden the sell-side JavaScript and that you have a reference to the TestAdSelectionManager and AdSelectionConfig used in the previous section.

In order to reset the overrides for all AdSelectionConfigs :

1. Call the asynchronous resetAllAdSelectionConfigRemoteOverrides() method with the relevant OutcomeReceiver object.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

After you reset sell-side overrides, calls to selectAds() use whatever decisionLogicUrl is stored in the AdSelectionConfig to attempt to fetch the required JavaScript.

If the call to resetAllAdSelectionConfigRemoteOverrides() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, AdServiceException indicates IllegalStateException as the cause.

Override buy-side JavaScript

1. Follow the steps to join a custom audience
2. Build an AddCustomAudienceOverrideRequest with the buyer and name of the custom audience you need to override, in addition to the bidding logic and data you want to use as an override.
3. Call the asynchronous overrideCustomAudienceRemoteInfo() method with the AddCustomAudienceOverrideRequest object and relevant Executor and OutcomeReceiver objects.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

The values for buyer and name are the same ones used to create the custom audience. Learn more about these fields .

Additionally, you can specify two additional parameters:

• biddingLogicJs : JavaScript that holds the buyer's logic that is used during ad selection. See the required function signatures in this JavaScript.
• trustedBiddingSignals : Bidding signals to be used during ad selection. For testing purposes this can be an empty string.

The asynchronous overrideCustomAudienceRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Subsequent calls to selectAds() use whatever bidding and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions.

• If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
• If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset buy-side overrides

This section assumes that you have overridden the buy-side JavaScript and that you have a reference to the TestCustomAudienceManager used in the previous section.

To reset overrides for all custom audiences:

1. Call the asynchronous resetAllCustomAudienceOverrides() method with relevant Executor and OutcomeReceiver objects.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

After you reset buy-side overrides, subsequent calls to selectAds() use whatever biddingLogicUrl and trustedBiddingData is stored in the CustomAudience to attempt to fetch the required JavaScript.

If the call to resetCustomAudienceRemoteInfoOverride() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Set Up a Reporting Server

When you use remote fetching overrides, you'll still need to set up a server that your device or emulator can reach to respond to reporting events. An endpoint that returns 200 is sufficient for testing. The GitHub repository includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

When looking for the OpenAPI definitions, look for the reporting-server.json. This file contains an endpoint that returns 200, representing an HTTP response code. This endpoint is used during selectAds() and signals to the Protected Audience API that impression reporting completed successfully.

Functionality to test

• Exercise joining or leaving and setting up a custom audience based on prior user actions.
• Exercise the initiation of on-device ad selection through JavaScripts hosted remotely.
• Observe how an app's association with custom audience settings may affect ad selection outcomes.
• Exercise impression reporting after ad selection.

محدودیت‌ها

The following table lists limitations for the Protected Audience API processing. The limits presented could be subject to change based on feedback. For in-progress capabilities, read the release notes .

گزارش اشکالات و مشکلات

Your feedback is a crucial part of the Privacy Sandbox on Android! Let us know of any issues you find or ideas for improving Privacy Sandbox on Android.