คู่มือนักพัฒนาซอฟต์แวร์ของ Protected Audience API

ขณะอ่านเอกสารประกอบเกี่ยวกับ Privacy Sandbox บน Android ให้ใช้ปุ่มDeveloper Preview หรือเบต้าเพื่อเลือก เวอร์ชันโปรแกรมที่คุณกำลังใช้งาน เนื่องจากวิธีการอาจแตกต่างกัน

Protected Audience API ใน Android (ก่อนหน้านี้เรียกว่า FLEDGE) มี Custom Audience API และ Ad Selection API แพลตฟอร์มเทคโนโลยีโฆษณาและผู้ลงโฆษณา สามารถใช้ API เหล่านี้เพื่อแสดงโฆษณาที่ปรับแต่งตามการมีส่วนร่วมกับแอปก่อนหน้า ซึ่ง จำกัดการแชร์ตัวระบุในแอปต่างๆ และจำกัดการแชร์ข้อมูลการโต้ตอบกับแอปของผู้ใช้ กับบุคคลที่สาม

Custom Audience API มุ่งเน้นไปที่การแยก "กลุ่มเป้าหมายที่กำหนดเอง" ซึ่งแสดงถึงกลุ่มผู้ใช้ที่มีความตั้งใจร่วมกัน ผู้ลงโฆษณาสามารถลงทะเบียนผู้ใช้ที่มีกลุ่มเป้าหมายที่กำหนดเองและเชื่อมโยงโฆษณาที่เกี่ยวข้อง กับกลุ่มเป้าหมายนั้นได้ ข้อมูลนี้จะจัดเก็บไว้ในเครื่องและสามารถใช้เพื่อแจ้งให้ผู้ลงโฆษณา ทราบถึงราคาเสนอ การกรองโฆษณา และการแสดงโฆษณา

Ad Selection API มีเฟรมเวิร์กที่ช่วยให้นักพัฒนาแอปหลายราย เรียกใช้การประมูลในเครื่องสำหรับกลุ่มเป้าหมายที่กำหนดเองได้ เพื่อให้บรรลุเป้าหมายนี้ ระบบ จะพิจารณาโฆษณาที่เกี่ยวข้องซึ่งเชื่อมโยงกับกลุ่มเป้าหมายที่กำหนดเอง และ ทำการประมวลผลเพิ่มเติมในโฆษณาที่แพลตฟอร์มเทคโนโลยีโฆษณาส่งคืนไปยังอุปกรณ์

แพลตฟอร์มเทคโนโลยีโฆษณาสามารถผสานรวม API เหล่านี้เพื่อใช้รีมาร์เก็ตติ้งที่ รักษาความเป็นส่วนตัวของผู้ใช้ เราวางแผนที่จะรองรับกรณีการใช้งานเพิ่มเติม รวมถึงโฆษณาเพื่อการติดตั้งแอป ในรุ่นต่อๆ ไป ดูข้อมูลเพิ่มเติมเกี่ยวกับ Protected Audience API ใน Android ได้ในข้อเสนอการออกแบบ

คู่มือนี้อธิบายวิธีทำงานกับ Protected Audience API ใน Android เพื่อทำสิ่งต่อไปนี้

  1. จัดการกลุ่มเป้าหมายที่กำหนดเอง
  2. ตั้งค่าและเรียกใช้การเลือกโฆษณาในอุปกรณ์
  3. รายงานการแสดงโฆษณา

ก่อนเริ่มต้น

ก่อนเริ่มต้น ให้ทำสิ่งต่อไปนี้

  1. ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์สำหรับ Privacy Sandbox ใน Android
  2. ติดตั้งอิมเมจระบบลงในอุปกรณ์ที่รองรับหรือตั้งค่า โปรแกรมจำลองที่รองรับ Privacy Sandbox ใน Android

  3. ในเทอร์มินัล ให้เปิดใช้การเข้าถึง Protected Audience API (ปิดใช้โดยค่าเริ่มต้น) ด้วยคำสั่ง adb ต่อไปนี้

      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 ไว้ในไฟล์ Manifest ของแอป 

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

  6. อ้างอิงการกำหนดค่าบริการโฆษณาในองค์ประกอบ <application> ของ ไฟล์ Manifest

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

  7. ระบุทรัพยากร XML ของบริการโฆษณาที่อ้างอิงในไฟล์ Manifest เช่น res/xml/ad_services_config.xml ดูข้อมูลเพิ่มเติมเกี่ยวกับสิทธิ์ของบริการโฆษณา และการควบคุมการเข้าถึง SDK

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

  8. โดยค่าเริ่มต้น Ad Selection API จะบังคับใช้ขีดจํากัด เกี่ยวกับปริมาณหน่วยความจําสูงสุดที่สคริปต์การประมูลหรือการรายงานผลการแสดงผล สามารถจัดสรรได้ ฟีเจอร์การจำกัดหน่วยความจำต้องใช้ WebView เวอร์ชัน 105.0.5195.58 ขึ้นไป แพลตฟอร์มจะบังคับใช้การตรวจสอบเวอร์ชันและการเรียกใช้ API selectAds และ reportImpression จะไม่สำเร็จหากไม่เป็นไปตามข้อกำหนดนี้ โดยมี 2 ตัวเลือกในการตั้งค่าดังนี้

    • ตัวเลือกที่ 1: เรียกใช้คำสั่ง adb ต่อไปนี้เพื่อปิดใช้งานการตรวจสอบนี้

      adb device_config put fledge_js_isolate_enforce_max_heap_size false

    • ตัวเลือกที่ 2: ติดตั้ง WebView Beta จาก Google Play Store ซึ่งต้องเท่ากับหรือสูงกว่าเวอร์ชันที่ระบุไว้ก่อนหน้านี้

เข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง

กลุ่มเป้าหมายที่กําหนดเองแสดงถึงกลุ่มผู้ใช้ที่มีความตั้งใจหรือ ความสนใจร่วมกันตามที่แอปของผู้ลงโฆษณากําหนด แอปหรือ SDK อาจใช้กลุ่มเป้าหมายที่กําหนดเอง เพื่อระบุกลุ่มเป้าหมายที่เฉพาะเจาะจง เช่น ผู้ที่ทิ้งสินค้าไว้ใน รถเข็นช็อปปิ้ง หากต้องการสร้างหรือเข้าร่วมกลุ่มเป้าหมายที่กำหนดเองแบบไม่พร้อมกัน ให้ทำดังนี้

  1. เริ่มต้นออบเจ็กต์ CustomAudienceManager
  2. สร้างออบเจ็กต์ CustomAudience โดยระบุพารามิเตอร์หลัก เช่น แพ็กเกจของผู้ซื้อและชื่อที่เกี่ยวข้อง จากนั้นเริ่มต้นออบเจ็กต์ JoinCustomAudienceRequest ด้วยออบเจ็กต์ CustomAudience
  3. เรียกใช้ joinCustomAudience() แบบอะซิงโครนัสด้วยออบเจ็กต์ JoinCustomAudienceRequest และออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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)

Java

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 โดยใช้พารามิเตอร์ที่จำเป็นต่อไปนี้

พารามิเตอร์ที่ไม่บังคับสำหรับออบเจ็กต์ CustomAudience อาจรวมถึง

  • เวลาเปิดใช้งาน: กลุ่มเป้าหมายที่กําหนดเองจะเข้าร่วมการเลือกโฆษณา และการอัปเดตรายวันได้หลังจากเวลาเปิดใช้งานเท่านั้น ซึ่งอาจมีประโยชน์ในการดึงดูดผู้ใช้ที่เลิกใช้แอปกลับมา เป็นต้น
  • เวลาหมดอายุ: เวลาในอนาคตหลังจากที่ระบบนำกลุ่มเป้าหมายที่กำหนดเองออกจากอุปกรณ์
  • สัญญาณการเสนอราคาของผู้ใช้: สตริง JSON ที่มีสัญญาณของผู้ใช้ เช่น ภาษาที่ผู้ใช้ต้องการ ซึ่ง JavaScript ตรรกะการเสนอราคาของผู้ซื้อใช้ เพื่อสร้างราคาเสนอในระหว่างกระบวนการเลือกโฆษณา รูปแบบนี้ช่วยให้แพลตฟอร์มเทคโนโลยีโฆษณา นำโค้ดกลับมาใช้ซ้ำในแพลตฟอร์มต่างๆ และช่วยให้ใช้ฟังก์ชัน JavaScript ได้ง่ายขึ้น
  • ข้อมูลการเสนอราคาที่เชื่อถือได้: URL HTTPS และรายการสตริงที่ใช้ในระหว่างกระบวนการเลือกโฆษณาซึ่งดึงสัญญาณการเสนอราคาจากบริการคีย์/ค่าที่เชื่อถือได้
  • โฆษณา: รายการออบเจ็กต์ AdData ที่สอดคล้องกับโฆษณาที่ เข้าร่วมในการเลือกโฆษณา ออบเจ็กต์ AdData แต่ละรายการประกอบด้วยข้อมูลต่อไปนี้
    • URL การแสดงผล: HTTPS URL ที่มีการค้นหาเพื่อแสดงโฆษณาสุดท้าย
    • ข้อมูลเมตา: ออบเจ็กต์ JSON ที่แปลงเป็นสตริงซึ่งมีข้อมูลที่ตรรกะการเสนอราคาของผู้ซื้อจะใช้ในระหว่างกระบวนการเลือกโฆษณา
    • ตัวกรองโฆษณา: คลาสที่มีข้อมูลที่จำเป็นทั้งหมดสำหรับการกรองโฆษณาเพื่อกระตุ้นการติดตั้งแอป และการจำกัดความถี่สูงสุดระหว่างการเลือกโฆษณา

ตัวอย่างการเริ่มต้นออบเจ็กต์ CustomAudience มีดังนี้

Kotlin

// 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()

Java

// 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();

จัดการผลลัพธ์ของ joinCustomAudience()

เมธอด joinCustomAudience() แบบอะซิงโครนัสใช้ออบเจ็กต์ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

  • การเรียกกลับ onResult() แสดงว่าสร้างหรืออัปเดตกลุ่มเป้าหมายที่กำหนดเองสำเร็จแล้ว
  • การเรียกกลับ onError() แสดงถึงเงื่อนไข 2 อย่างที่เป็นไปได้
    • หากเริ่มต้น JoinCustomAudienceRequest ด้วยอาร์กิวเมนต์ที่ไม่ถูกต้อง AdServicesException จะระบุ IllegalArgumentException เป็นสาเหตุ
    • ข้อผิดพลาดอื่นๆ ทั้งหมดจะได้รับ AdServicesException พร้อมIllegalStateException เป็นสาเหตุ

ตัวอย่างการจัดการผลลัพธ์ของ joinCustomAudience()

Kotlin

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

Java

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 ที่เกี่ยวข้อง

Kotlin

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)

Java

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

OutcomeReceiver จะส่งสัญญาณ สิ้นสุดการเรียก API เช่นเดียวกับการเรียก joinCustomAudience() ผลลัพธ์ข้อผิดพลาดจะไม่แยกความแตกต่างระหว่างข้อผิดพลาดภายในและอาร์กิวเมนต์ที่ไม่ถูกต้องเพื่อช่วยปกป้องความเป็นส่วนตัว ระบบจะเรียกใช้onResult() การเรียกกลับเมื่อการเรียก API เสร็จสมบูรณ์ ไม่ว่าจะนำ กลุ่มเป้าหมายที่กำหนดเองที่ตรงกันออกสำเร็จหรือไม่ก็ตาม

เรียกใช้การเลือกโฆษณา

หากต้องการใช้ Protected Audience API เพื่อเลือกโฆษณา ให้เรียกใช้เมธอด selectAds()

  1. เริ่มต้นออบเจ็กต์ AdSelectionManager
  2. สร้างออบเจ็กต์ AdSelectionConfig
  3. เรียกใช้เมธอด selectAds() แบบอะซิงโครนัสด้วยออบเจ็กต์ AdSelectionConfig รวมถึงออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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
)

Java

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 โดยคุณต้องระบุพารามิเตอร์ที่จำเป็นต่อไปนี้

  • ผู้ขาย: ตัวระบุสำหรับเครือข่ายโฆษณาของผู้ขายที่เริ่มการเลือกโฆษณา
  • URL ตรรกะการตัดสินใจ: HTTPS URL ที่มีการค้นหาเพื่อรับตรรกะ JavaScript ของเครือข่ายโฆษณาของผู้ขาย
    • HTTPS URL: ส่งคำค้นหาเพื่อรับตรรกะ JavaScript ของเครือข่ายโฆษณาของผู้ขาย ดูลายเซ็นฟังก์ชันที่จำเป็น
    • URI ที่สร้างไว้ล่วงหน้า: ที่เป็นไปตามรูปแบบการเลือกโฆษณาของ FLEDGE IllegalArgumentException จะแสดงขึ้นหากมีการส่ง URI ที่สร้างไว้ล่วงหน้าซึ่งไม่รองรับหรือมีรูปแบบไม่ถูกต้อง
  • ผู้ซื้อกลุ่มเป้าหมายที่กำหนดเอง: รายการตัวระบุทั้งหมดสำหรับเครือข่ายโฆษณาของผู้ซื้อ ที่ผู้ขายอนุญาตให้เข้าร่วมกระบวนการเลือกโฆษณา ตัวระบุผู้ซื้อเหล่านี้สอดคล้องกับ CustomAudience.getBuyer() ของ กลุ่มเป้าหมายที่กำหนดเองที่เข้าร่วม

คุณเลือกกำหนดพารามิเตอร์ต่อไปนี้เพื่อการเลือกโฆษณาที่ปรับแต่งมากขึ้นได้

  • สัญญาณการเลือกโฆษณา: ออบเจ็กต์ JSON ที่แปลงเป็นสตริงซึ่งมี สัญญาณที่ตรรกะการเสนอราคาของผู้ซื้อ JavaScript จะใช้ซึ่งดึงมาจาก CustomAudience.getBiddingLogicUrl()
  • สัญญาณของผู้ขาย: ออบเจ็กต์ JSON ที่แปลงเป็นสตริงซึ่งมีสัญญาณ ที่ตรรกะการตัดสินใจ JavaScript ที่ดึงข้อมูลของผู้ขายใช้จาก AdSelectionConfig.getDecisionLogicUrl()
  • สัญญาณต่อผู้ซื้อ: แผนที่ของออบเจ็กต์ JSON ที่ซีเรียลไลซ์เป็นสตริง ซึ่งมีสัญญาณที่ตรรกะการเสนอราคา JavaScript ของผู้ซื้อที่เฉพาะเจาะจงจะใช้ ซึ่งดึงมาจาก CustomAudience.getBiddingLogicUrl() ซึ่งระบุโดย ฟิลด์ผู้ซื้อของกลุ่มเป้าหมายที่กำหนดเองที่เข้าร่วม
  • โฆษณาตามบริบท: กลุ่มโฆษณาที่รวบรวมโดยตรง จากผู้ซื้อระหว่างการประมูลที่เกิดขึ้นนอกการประมูล Protected Audience

เมื่อเลือกโฆษณาแล้ว ระบบจะบันทึกผลลัพธ์ ราคาเสนอ และสัญญาณไว้ภายใน เพื่อการรายงาน OutcomeReceiver.onResult() Callback จะแสดงผล AdSelectionOutcome ที่มีข้อมูลต่อไปนี้

  • URL การแสดงผลสำหรับโฆษณาที่ชนะซึ่งได้จาก AdData.getRenderUrl()
  • รหัสการเลือกโฆษณาที่ไม่ซ้ำกันสำหรับผู้ใช้อุปกรณ์ รหัสนี้ใช้สำหรับการรายงาน การแสดงผลโฆษณา

หากเลือกโฆษณาไม่สำเร็จเนื่องจากเหตุผลต่างๆ เช่น อาร์กิวเมนต์ไม่ถูกต้อง การหมดเวลา หรือการใช้ทรัพยากรมากเกินไป OutcomeReceiver.onError() การเรียกกลับจะให้ AdServicesException พร้อมลักษณะการทำงานต่อไปนี้

  • หากการเลือกโฆษณาเริ่มต้นด้วยอาร์กิวเมนต์ที่ไม่ถูกต้อง AdServicesException จะระบุ IllegalArgumentException เป็นสาเหตุ
  • ข้อผิดพลาดอื่นๆ ทั้งหมดจะได้รับ AdServicesException พร้อมIllegalStateException เป็นสาเหตุ

โฆษณาตามบริบท

Protected Audience สามารถรวมโฆษณาตามบริบทในการประมูลที่ได้รับการปกป้อง ระบบจะต้องเลือกโฆษณาตามบริบทในเซิร์ฟเวอร์เทคโนโลยีโฆษณาและแสดงผลไปยัง อุปกรณ์ภายนอก Protected Audience API จากนั้นจะรวมโฆษณาตามบริบท ในการประมูลได้โดยใช้ AdSelectionConfig ซึ่งจะทําให้โฆษณาทํางาน เหมือนกับโฆษณาในอุปกรณ์ รวมถึงมีสิทธิ์ในการกรองโฆษณาเชิงลบ เมื่อ การประมูล Protected Audience API เสร็จสมบูรณ์แล้ว คุณต้องเรียกใช้ reportImpression() ซึ่งจะเรียกใช้ reportWin() ในโฆษณาตามบริบทที่ชนะ ในรูปแบบเดียวกับการรายงานการแสดงผล เพื่อรับโฆษณาที่ชนะในอุปกรณ์ โฆษณาตามบริบทแต่ละรายการต้องมีผู้ซื้อ การเสนอราคา ลิงก์ไปยังตรรกะการรายงาน URL การแสดงผล และข้อมูลเมตาของโฆษณา

หากต้องการแสดงโฆษณาตามบริบทในแอป แอปเป้าหมายต้องสร้างออบเจ็กต์ ContextualAds ดังนี้

Kotlin

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

Java

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

จากนั้นคุณจะส่งออบเจ็กต์ ContextualAds ที่ได้เมื่อสร้างAdSelectionConfig ได้

Kotlin

// 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)

Java

// 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);

การกรองโฆษณาเพื่อการติดตั้งแอป

การกรองโฆษณาเพื่อการติดตั้งแอปช่วยให้คุณกรองโฆษณาเพื่อการติดตั้งสำหรับแอป ที่ติดตั้งไว้ในอุปกรณ์แล้ว

ขั้นตอนแรกในกระบวนการนี้คือการกำหนดว่าผู้ลงโฆษณารายใดมีสิทธิ์ กรองแพ็กเกจที่ติดตั้ง คุณต้องดำเนินการนี้ในแอปที่ต้องการ กำหนดเป้าหมายด้วยโฆษณา

Kotlin

//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)
    }
  })

Java

//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 ด้วยข้อมูลเกี่ยวกับโฆษณาที่ เกี่ยวข้องกับแอปที่ต้องการกรองออก

Kotlin

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

Java

// 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 ใหม่ด้วย

Kotlin

// 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()

Java

// 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();

การกรองความถี่สูงสุด

การกรองความถี่สูงสุดช่วยให้เทคโนโลยีโฆษณาสามารถจำกัดจำนวนครั้งที่โฆษณาแสดงได้ การกรองความถี่สูงสุดช่วยลดการแสดงโฆษณามากเกินไปและเพิ่มประสิทธิภาพการเลือกโฆษณา สำรองสำหรับแคมเปญโฆษณาที่กำหนด

ตัวกรองการจำกัดความถี่มีองค์ประกอบหลัก 2 อย่าง ได้แก่ ประเภทเหตุการณ์โฆษณา และ คีย์ตัวนับโฆษณา ประเภทเหตุการณ์โฆษณาที่ใช้ได้มีดังนี้

  • ชนะ: เหตุการณ์ชนะระบุว่าโฆษณาชนะการประมูล Protected Audience API จะอัปเดตเหตุการณ์ที่ชนะโดยอัตโนมัติ และนักพัฒนาซอฟต์แวร์ไม่สามารถเรียกใช้เหตุการณ์ที่ชนะได้โดยตรง ข้อมูลการชนะจะแสดงต่อโฆษณาภายใน กลุ่มเป้าหมายที่กำหนดเองที่ระบุเท่านั้น
  • การแสดงผล: แยกจาก reportImpression ผู้เรียกใช้ในอุปกรณ์ (SSP หรือ MMP) จะใช้ updateAdCounterHistogram() เพื่อเรียกใช้เหตุการณ์การแสดงผล ณ จุดในโค้ดที่เลือก เหตุการณ์การแสดงผลจะปรากฏต่อโฆษณาทั้งหมดที่อยู่ใน DSP ที่กำหนด และไม่ได้จำกัดเฉพาะโฆษณาในกลุ่มเป้าหมายที่กำหนดเองเดียวกัน
  • ดู: ผู้เรียกใช้ในอุปกรณ์ (SSP หรือ MMP) จะเรียกใช้เหตุการณ์ ณ จุดในโค้ดที่เลือกโดยใช้การเรียกไปยัง updateAdCounterHistogram() เหตุการณ์การดูจะ มองเห็นได้ในโฆษณาทั้งหมดที่อยู่ใน DSP ที่กำหนด และไม่ได้จำกัดเฉพาะโฆษณาใน กลุ่มเป้าหมายที่กำหนดเองเดียวกัน
  • คลิก: เหตุการณ์จะเรียกใช้โดยผู้เรียกในอุปกรณ์ (SSP หรือ MMP) ณ จุดในโค้ดที่เลือกโดยใช้การเรียกไปยัง updateAdCounterHistogram() เหตุการณ์คลิก จะมองเห็นได้ในโฆษณาทั้งหมดที่อยู่ใน DSP ที่กำหนด และไม่ได้จำกัดเฉพาะโฆษณาใน กลุ่มเป้าหมายที่กำหนดเองเดียวกัน

ในแอปของผู้เผยแพร่โฆษณา SSP หรือ MMP ที่มีอยู่ในอุปกรณ์จะเรียกใช้เหตุการณ์โฆษณา เมื่อมีการเรียกใช้ updateAdCounterHistogram() ระบบจะเพิ่มตัวนับของตัวกรองความถี่สูงสุดเพื่อให้การประมูลในอนาคตมีข้อมูลล่าสุดเกี่ยวกับการแสดงโฆษณาที่กำหนดต่อผู้ใช้ ประเภทเหตุการณ์โฆษณาไม่ได้ เชื่อมโยงกับการกระทําของผู้ใช้ที่เกี่ยวข้องอย่างชัดเจน และเป็นหลักเกณฑ์ที่ให้ไว้เพื่อช่วย ผู้เรียกในการจัดโครงสร้างระบบเหตุการณ์ หากต้องการเพิ่มตัวนับโฆษณาในเวลาที่เกิดเหตุการณ์ ขึ้น ผู้ดำเนินการในอุปกรณ์จะต้องระบุรหัสการเลือกโฆษณาของการประมูลโฆษณาที่ชนะ

คีย์ตัวนับโฆษณาคือจำนวนเต็มแบบมีเครื่องหมาย 32 บิตที่กำหนดโดยเทคโนโลยีโฆษณาของผู้ซื้อ และสอดคล้องกับชุดโฆษณาที่กำหนดโดย DSP เนื่องจากคีย์ตัวนับโฆษณาใช้ได้เฉพาะกับโฆษณาที่อยู่ใน DSP ที่กำหนดเท่านั้น จึงเลือกคีย์เหล่านี้ได้โดยไม่ทับซ้อนกับฮิสโตแกรมจากเทคโนโลยีโฆษณาอื่น ระบบจะใช้คีย์ตัวนับโฆษณาเพื่อเพิ่มตัวระบุเฉพาะ DSP ในโฆษณาของ DSP หรือภายในกลุ่มเป้าหมายที่กำหนดเองที่ระบุ เพื่อกรองโฆษณาจากการประมูลในอนาคต

สามารถใช้ประโยชน์จากคีย์ตัวนับเพื่อจัดลําดับความสําคัญของโฆษณาที่มีแนวโน้มที่จะ น่าสนใจสําหรับผู้ใช้ที่เฉพาะเจาะจงตามการโต้ตอบกับโฆษณาอื่นๆ จาก เทคโนโลยีโฆษณาของผู้ซื้อที่เฉพาะเจาะจง ตัวอย่างเช่น โฆษณาที่ได้รับการมีส่วนร่วมในระดับสูง จากการประมูลโฆษณาที่ชนะ การดู และการคลิก แสดงถึงจุดข้อมูลที่อนุมานได้ เพื่ออธิบายประเด็นนี้เพิ่มเติม โฆษณาสำหรับไม้กอล์ฟสำหรับคนถนัดซ้าย อาจบ่งบอกว่าผู้ใช้ไม่สนใจไม้กอล์ฟสำหรับคนถนัดขวา ตัวกรองความถี่สูงสุดที่ตั้งค่าไว้สำหรับคีย์ตัวนับที่กำหนดให้กับโฆษณาสำหรับผู้ถนัดซ้ายอาจ กรองโฆษณาสำหรับไม้กอล์ฟสำหรับผู้ถนัดขวาออก

หากต้องการใช้การกำหนดความถี่สูงสุดในการประมูล คุณต้องสร้าง KeyedFrequencyCapออบเจ็กต์ก่อน

Kotlin

// 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()

Java

// 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 ได้

Kotlin

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

Java

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

เมื่อระบบสร้างAdFiltersออบเจ็กต์ด้วยตัวกรองการกำหนดความถี่สูงสุด คุณจะส่งต่อออบเจ็กต์ได้เมื่อสร้างกลุ่มเป้าหมายที่กำหนดเอง

Kotlin

// 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()

Java

// 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 จะเรียกใช้เหตุการณ์คลิก การดู หรือการแสดงผลที่จำเป็นได้

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

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

เรียกใช้ JavaScript การรายงานของคุณเองขณะใช้ URI ที่สร้างไว้ล่วงหน้า

ปัจจุบันแพลตฟอร์ม Privacy Sandbox มีการติดตั้งใช้งาน JavaScript การรายงานพื้นฐานเท่านั้นสําหรับ URI ที่สร้างไว้ล่วงหน้า หากต้องการเรียกใช้ JavaScript การรายงานของคุณเองในขณะที่ยังใช้ 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);

เรียกใช้สื่อกลาง Waterfall

การแสดงโฆษณาสื่อกลางตามลำดับชั้นต้องใช้ SDK ของบุคคลที่สามหลายรายการ (เครือข่าย 3P) ซึ่งต้อง ได้รับการจัดการโดยเครือข่ายสื่อกลาง SDK ของบุคคลที่หนึ่ง การใช้สื่อกลางแบบลำดับขั้นจะ ดำเนินการในลักษณะเดียวกันไม่ว่าการประมูลจะเกิดขึ้นในอุปกรณ์หรือทำงานใน บริการเสนอราคาและการประมูล (B&A)

เครือข่ายของบุคคลที่สาม

เครือข่ายบุคคลที่สามต้องมีอแดปเตอร์ที่อนุญาตให้เครือข่ายสื่อกลาง เรียกใช้เมธอดที่จำเป็นสำหรับการประมูล

  • เรียกใช้การเลือกโฆษณา
  • การแสดงผลของรายงาน

ตัวอย่างอแดปเตอร์เครือข่ายสื่อกลางมีดังนี้

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

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 รายการเดียวสำหรับการรายงาน)

เครือข่ายสื่อกลาง

เครือข่ายสื่อกลางต้องมีการติดตั้งใช้งาน selectAds และ reportImpression เช่นเดียวกับเครือข่ายบุคคลที่สาม ดูข้อมูลเพิ่มเติมได้ที่ส่วนเกี่ยวกับวิธีเรียกใช้การเลือกโฆษณาและวิธีรายงานการแสดงผลโฆษณา

เครือข่ายสื่อกลางมีหน้าที่เรียกใช้เชนสื่อกลางและวางตำแหน่งตัวเองในเชนสื่อกลาง ส่วนถัดไปจะอธิบายวิธีตั้งค่าและ เรียกใช้กระบวนการนี้

เรียกข้อมูลเชนสื่อกลางและราคาพื้น

เครือข่ายสื่อกลางมีหน้าที่ดึงโฆษณาตามบริบทของบุคคลที่หนึ่ง (1P) เชนสื่อกลาง และราคาพื้นของราคาเสนอของเครือข่ายบุคคลที่สาม (3P) ซึ่งอาจเกิดขึ้นในคำขอเพื่อดึงโฆษณาตามบริบทที่ดำเนินการโดยเครือข่ายสื่อกลาง ห่วงโซ่สื่อกลางจะกำหนดวิธีวนซ้ำผ่านเครือข่ายบุคคลที่สาม และสามารถส่งราคาพื้นฐานของราคาเสนอไปยังกระบวนการประมูลเป็น adSelectionSignals ได้

การวางตำแหน่งเครือข่ายในเชนสื่อกลาง

SDK สื่อกลางสามารถวางตัวเองในเชนสื่อกลางตาม eCPM แบบเรียลไทม์ ของราคาเสนอโฆษณาของบุคคลที่หนึ่ง ใน Protected Audience API ราคาเสนอโฆษณาจะทึบแสง SDK สื่อกลาง ควรใช้ AdSelectionFromOutcomesConfig เพื่อเปรียบเทียบราคาเสนอของโฆษณา 1P ที่ระบุกับราคาพื้นของเครือข่าย 3P ถัดไปในเชนได้ หากราคาเสนอของบุคคลที่หนึ่งสูงกว่าราคาพื้น ระบบจะวาง SDK สื่อกลางไว้หน้าเครือข่ายบุคคลที่สามนั้น

เรียกใช้การเลือกโฆษณา

หากต้องการดึงผู้ลงโฆษณาบุคคลที่หนึ่งที่เป็นไปได้ เครือข่ายสื่อกลางสามารถเรียกใช้การประมูลในอุปกรณ์ โดยทำตามขั้นตอนในส่วนเรียกใช้การเลือกโฆษณา ซึ่งจะสร้างผู้มีสิทธิ์เป็นโฆษณาฝั่ง 1P, ราคาเสนอ และ AdSelectionId ที่ใช้ในกระบวนการสื่อกลาง

สร้าง AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig ช่วยให้เครือข่ายสื่อกลางส่งรายการ AdSelectionIds (ผลลัพธ์จากการประมูลครั้งก่อน), สัญญาณการเลือกโฆษณา และ URI เพื่อดึงข้อมูล JavaScript ที่เลือกโฆษณาจากผู้ลงโฆษณาหลายรายได้ ระบบจะส่งรายการ AdSelectionId พร้อมด้วยราคาเสนอและสัญญาณไปยัง JavaScript ซึ่งสามารถแสดงผลรายการใดรายการหนึ่งใน AdSelectionIds หากชนะราคาเสนอขั้นต่ำ หรือไม่แสดงผลหากควรดำเนินการต่อในเชนสื่อกลาง

เครือข่ายสื่อกลางสร้าง AdSelectionFromOutcomesConfig โดยใช้ 1P AdSelectionId จากส่วนก่อนหน้า และราคาพื้นฐานสำหรับการเสนอราคาของเครือข่ายบุคคลที่สาม ที่กำลังพิจารณา ควรสร้าง AdSelectionFromOutcomesConfig ใหม่ สำหรับแต่ละขั้นตอนในเชนสื่อกลาง

Kotlin

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

Java

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() ที่ทำงานก่อนหน้าสำหรับโฆษณา 1P
  • สัญญาณการเลือกโฆษณา: ออบเจ็กต์ JSON ที่แปลงเป็นสตริงซึ่งมี สัญญาณที่ตรรกะการเสนอราคาของผู้ซื้อจะใช้ ในกรณีนี้ ให้รวมราคาเสนอขั้นต่ำ ที่เรียกข้อมูลมาสำหรับเครือข่ายบุคคลที่สามที่ระบุ
  • URI ของตรรกะการเลือก: URL HTTPS ที่มีการค้นหาในระหว่างการเลือกโฆษณาเพื่อดึงข้อมูล JavaScript ของเครือข่ายสื่อกลางสําหรับการเลือกโฆษณาที่ชนะ ดูลายเซ็นฟังก์ชันที่จำเป็นใน JavaScript นี้ JavaScript ควรแสดงโฆษณาของบุคคลที่สามหากราคาเสนอสูงกว่าราคาพื้น หรือแสดง null ในกรณีอื่นๆ ซึ่งช่วยให้ SDK สื่อกลางตัดเชนสื่อกลางได้เมื่อพบผู้ชนะ

เมื่อสร้าง AdSelectionOutcomesConfig แล้ว ให้เรียกใช้เมธอด selectAds() ของ เครือข่าย 3P ที่อยู่แรกในเชน

Kotlin

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)

Java

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

จัดระเบียบสื่อกลาง Waterfall

ลำดับการดำเนินการสำหรับการเรียกใช้กระบวนการสื่อกลางมีดังนี้

  1. เรียกใช้การเลือกโฆษณาของบุคคลที่หนึ่ง
  2. วนซ้ำในเชนสื่อกลาง สำหรับเครือข่ายบุคคลที่สามแต่ละเครือข่าย ให้ทำดังนี้
    1. สร้าง AdSelectionFromOutcomeConfig รวมถึง outcomeId ของบุคคลที่หนึ่งและราคาพื้นฐานของราคาเสนอของ SDK บุคคลที่สาม
    2. เรียกใช้ selectAds() ด้วยการกำหนดค่าจากขั้นตอนก่อนหน้า
    3. หากผลลัพธ์ไม่ว่างเปล่า ให้แสดงผลโฆษณา
    4. เรียกใช้เมธอด selectAds() ของอะแดปเตอร์เครือข่าย SDK ปัจจุบัน หากผลลัพธ์ ไม่ว่างเปล่า ให้แสดงผลโฆษณา
  3. หากไม่พบผู้ชนะจากเชน ให้แสดงโฆษณา 1P

Kotlin

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

Java

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) { ... }
}

รายงานการแสดงโฆษณา

ขั้นตอนการรายงานการแสดงผลโฆษณามี 2 ขั้นตอน ขึ้นอยู่กับวิธีที่ใช้ในการประมูล หากคุณเป็น SSP รายเดียวที่จัดการประมูล ให้ทำตามส่วนนี้ หาก คุณจะใช้การแสดงโฆษณาสื่อกลางตามลำดับขั้น ให้ทำตามขั้นตอนในส่วนการรายงานการแสดงผลของการแสดงโฆษณาสื่อกลางตามลำดับขั้น

การรายงานการแสดงผล SSP รายการเดียว

หลังจากเลือกโฆษณาที่ชนะจากเวิร์กโฟลว์การเลือกโฆษณาแล้ว คุณจะ รายงานการแสดงผลกลับไปยังแพลตฟอร์มฝั่งผู้ซื้อและฝั่งผู้ขายที่เข้าร่วม ด้วยวิธีAdSelectionManager.reportImpression()ได้ วิธีรายงานการแสดงผลโฆษณา

  1. เริ่มต้นออบเจ็กต์ AdSelectionManager
  2. สร้างออบเจ็กต์ ReportImpressionRequest ด้วยรหัสการเลือกโฆษณา
  3. เรียกใช้เมธอด reportImpression() แบบอะซิงโครนัสด้วยออบเจ็กต์ ReportImpressionRequest รวมถึงออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Java

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

Kotlin

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() Callback จะระบุเงื่อนไขต่อไปนี้
    • หากมีการเริ่มต้นการเรียกใช้ด้วยอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง AdServicesException จะระบุ IllegalArgumentException เป็นสาเหตุ
    • ข้อผิดพลาดอื่นๆ ทั้งหมดจะได้รับ AdServicesException พร้อมIllegalStateException เป็นสาเหตุ

การรายงานการแสดงผลของสื่อกลางตามลำดับขั้น

SDK สื่อกลางต้องติดตาม SDK ที่ชนะเพื่อทริกเกอร์ขั้นตอนการรายงาน SDK ที่เข้าร่วมในเชนสื่อกลางควรมี เมธอดสำหรับสื่อกลางที่จะเรียกใช้เพื่อทริกเกอร์โฟลว์การรายงานของตนเอง SDK ที่เข้าร่วมการประมูลที่ใช้สื่อกลางสามารถทำตามขั้นตอนด้านบนเพื่อใช้การรายงานของตนเอง

SSP สามารถใช้ตัวอย่างโค้ด SDK ของบุคคลที่สามนี้เป็นต้นแบบสำหรับวิธีเข้าร่วมใน ขั้นตอนการทำงานของสื่อกลางได้

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

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

ปลายทางการรายงานการแสดงผล

API การแสดงผลรายงานจะส่งคำขอ HTTPS GET ไปยังอุปกรณ์ปลายทางที่แพลตฟอร์มฝั่งผู้ขายและแพลตฟอร์มฝั่งผู้ซื้อที่ชนะระบุไว้

ปลายทางของแพลตฟอร์มฝั่งซื้อ

  • API ใช้ URL ตรรกะการเสนอราคาที่ระบุในกลุ่มเป้าหมายที่กำหนดเองเพื่อ ดึงข้อมูล JavaScript ที่ผู้ซื้อระบุซึ่งมีตรรกะในการแสดงผล URL การรายงานผลการแสดงผล
  • เรียกใช้ฟังก์ชัน reportWin() JavaScript ซึ่งคาดว่าจะแสดงผล URL การรายงานการแสดงผลของผู้ซื้อ

ปลายทางของแพลตฟอร์มฝั่งขาย

  • ใช้ URL ตรรกะการตัดสินใจที่ระบุในออบเจ็กต์ AdSelectionConfig เพื่อดึงข้อมูล JavaScript ตรรกะการตัดสินใจของผู้ขาย
  • เรียกใช้reportResult()ฟังก์ชัน JavaScript ซึ่งคาดว่าจะแสดงผล URL การรายงานการแสดงผลของผู้ขาย

การรายงานบริการเสนอราคาและการประมูล

การประมูลที่ดำเนินการในบริการการเสนอราคาและการประมูลจะมีข้อมูลการรายงานที่จำเป็นทั้งหมด รวมถึง URL ที่สร้างขึ้นสำหรับการรายงานการโต้ตอบกับโฆษณา ซึ่งรวมอยู่ในการตอบกลับที่เข้ารหัสจากการประมูลฝั่งเซิร์ฟเวอร์ เมื่อถอดรหัส การตอบกลับแล้ว ระบบจะลงทะเบียน URL ที่เหมาะสมกับแพลตฟอร์ม ดังนั้น การรายงานโฆษณาและการแสดงผลจึงทำตามขั้นตอนเดียวกัน

การรายงานการแสดงผลอย่างเต็มที่

reportImpression() วิธีนี้ออกแบบมาเพื่อให้การรายงานเสร็จสมบูรณ์อย่างเต็มที่

รายงานการโต้ตอบกับโฆษณา

Protected Audience ให้การสนับสนุนในการรายงานการโต้ตอบที่ละเอียดยิ่งขึ้นสำหรับ โฆษณาที่แสดง ซึ่งอาจรวมถึงการโต้ตอบ เช่น เวลาในการดู การคลิก การวางเมาส์เหนือ หรือเมตริกอื่นๆ ที่มีประโยชน์ซึ่งรวบรวมได้ กระบวนการรับรายงานเหล่านี้มี 2 ขั้นตอน ก่อนอื่น ผู้ซื้อและผู้ขายต้องลงทะเบียนเพื่อรับรายงานเหล่านี้ใน JavaScript การรายงาน จากนั้นไคลเอ็นต์จะต้อง รายงานเหตุการณ์เหล่านี้

การลงทะเบียนเพื่อรับเหตุการณ์การโต้ตอบ

การลงทะเบียนสำหรับเหตุการณ์การโต้ตอบจะเกิดขึ้นในฟังก์ชัน JavaScript ของreportWin()ผู้ซื้อและreportResult()ผู้ขายโดยใช้ฟังก์ชัน JavaScript ที่แพลตฟอร์มระบุไว้: registerAdBeacon หากต้องการลงทะเบียนเพื่อรับรายงานเหตุการณ์ ให้เรียกใช้ฟังก์ชัน JavaScript ของแพลตฟอร์มจาก JavaScript การรายงาน ข้อมูลโค้ดต่อไปนี้ใช้ 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 ที่ส่งคืนก่อนหน้านี้
  • คีย์การโต้ตอบ: คีย์สตริงที่กำหนดโดยไคลเอ็นต์ซึ่งอธิบายการกระทำ ที่รายงาน ต้องตรงกับคีย์ที่ผู้ขายหรือผู้ซื้อลงทะเบียนไว้ในฟังก์ชัน JavaScript ของการรายงาน
  • ข้อมูลการโต้ตอบ: สตริงที่มีข้อมูลที่จะรวมไว้ในรายงานเหตุการณ์ เพื่อโพสต์กลับไปยังเซิร์ฟเวอร์การรายงาน
  • ปลายทางการรายงาน: บิตมาสก์ที่ระบุว่าควรรายงานเหตุการณ์ให้ผู้ซื้อ ผู้ขาย หรือทั้ง 2 ฝ่ายทราบ แพลตฟอร์มจะระบุค่าสถานะเหล่านี้ และสามารถสร้างมาสก์ปลายทางสุดท้ายได้โดยใช้การดำเนินการระดับบิต หากต้องการรายงานไปยังปลายทางเดียว คุณสามารถใช้ธงที่แพลตฟอร์มมีให้โดยตรง หากต้องการรายงานไปยังปลายทางหลายแห่ง คุณสามารถใช้ OR แบบบิตไวส์ (|) เพื่อรวมค่าแฟล็ก

เมธอด reportInteraction() แบบอะซิงโครนัสใช้ออบเจ็กต์ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

  • onResult() การเรียกกลับจะระบุว่าการเรียกรายงานการโต้ตอบนั้นถูกต้อง
  • onError() Callback จะระบุเงื่อนไขต่อไปนี้
    • หากมีการโทรเมื่อแอปทำงานในเบื้องหลัง ระบบจะแสดงผล IllegalStateException พร้อมคำอธิบายความล้มเหลว
    • หากไคลเอ็นต์ถูกจำกัดไม่ให้เรียกใช้ reportInteraction() ระบบจะแสดงผล LimitExceededException
    • หากไม่ได้ลงทะเบียนแพ็กเกจเพื่อเรียกใช้ API ที่รักษาความเป็นส่วนตัว ระบบจะแสดงผล a SecurityException()
    • หากแอปที่รายงานการโต้ตอบแตกต่างจากแอปที่เรียก selectAds() ระบบจะแสดงผล IllegalStateException
  • หากผู้ใช้ไม่ยินยอมให้เปิดใช้ Privacy Sandbox API การเรียกจะล้มเหลวโดยไม่มีข้อความแจ้ง

ปลายทางการรายงานการโต้ตอบ

API การโต้ตอบกับรายงานจะส่งคำขอ HTTPS POST ไปยังปลายทางที่แพลตฟอร์มฝั่งขายและแพลตฟอร์มฝั่งซื้อที่ชนะเป็นผู้ระบุ Protected Audience จะจับคู่คีย์การโต้ตอบกับ URI ที่ประกาศใน JavaScript การรายงาน และส่งคำขอ POST ไปยังปลายทางแต่ละรายการสำหรับการโต้ตอบแต่ละรายการที่รายงาน Content-Type ของคำขอเป็นข้อความธรรมดาโดยมีเนื้อหาเป็น ข้อมูลการโต้ตอบ

การรายงานการโต้ตอบอย่างเต็มความสามารถ

reportInteraction() ออกแบบมาเพื่อให้การรายงานผ่าน HTTP POST เสร็จสมบูรณ์อย่างเต็มความสามารถ

การอัปเดตในเบื้องหลังทุกวัน

เมื่อสร้างกลุ่มเป้าหมายที่กำหนดเอง แอปหรือ SDK จะเริ่มต้นข้อมูลเมตาของกลุ่มเป้าหมายที่กำหนดเองได้ นอกจากนี้ แพลตฟอร์มยังอัปเดตข้อมูลเมตาของกลุ่มเป้าหมายที่กำหนดเองต่อไปนี้ได้ด้วยกระบวนการอัปเดตเบื้องหลังรายวัน

  • สัญญาณการเสนอราคาของผู้ใช้
  • ข้อมูลการเสนอราคาที่เชื่อถือได้
  • AdData รายการ

กระบวนการนี้จะค้นหา URL การอัปเดตรายวันที่กำหนดไว้ในกลุ่มเป้าหมายที่กำหนดเอง และ URL อาจแสดงการตอบกลับ JSON

  • การตอบกลับ JSON อาจมีฟิลด์ข้อมูลเมตาที่รองรับซึ่งต้องอัปเดต
  • ระบบจะตรวจสอบความถูกต้องของแต่ละฟิลด์ JSON แยกกัน ไคลเอ็นต์จะละเว้นฟิลด์ที่ รูปแบบไม่ถูกต้อง ซึ่งส่งผลให้ไม่มีการอัปเดตฟิลด์นั้นในการตอบกลับ
  • การตอบกลับ HTTP ที่ว่างเปล่าหรือออบเจ็กต์ JSON ที่ว่างเปล่า "{}" จะทําให้ไม่มีการอัปเดตข้อมูลเมตา
  • ขนาดข้อความตอบกลับต้องไม่เกิน 10 KB
  • URI ทั้งหมดต้องใช้ HTTPS
  • trusted_bidding_uri ต้องแชร์ eTLD+1 เดียวกันกับผู้ซื้อ

ตัวอย่าง: การตอบกลับ JSON สำหรับการอัปเดตรายวันในเบื้องหลัง

{
    "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 สำหรับการเลือกโฆษณา

เวิร์กโฟลว์การเลือกโฆษณาจะประสานการดำเนินการ JavaScript ที่ผู้ซื้อและผู้ขายระบุ

ระบบจะดึงข้อมูล JavaScript ที่ผู้ซื้อระบุจาก URL ตรรกะการเสนอราคาที่ระบุใน กลุ่มเป้าหมายที่กำหนดเอง JavaScript ที่ส่งคืนควรมีฟังก์ชันต่อไปนี้

ระบบจะดึงข้อมูล JavaScript ที่ผู้ขายระบุจาก URL ตรรกะการตัดสินใจที่ระบุในพารามิเตอร์ AdSelectionConfig สำหรับ API การเลือกโฆษณา JavaScript ที่ส่งคืน ควรมีฟังก์ชันต่อไปนี้

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

พารามิเตอร์อินพุต

  • ad: ออบเจ็กต์ JSON ที่มีรูปแบบ var ad = { 'render_url': url, 'metadata': json_metadata };
  • auction_signals, per_buyer_signals: ออบเจ็กต์ JSON ที่ระบุในออบเจ็กต์การกำหนดค่าการประมูล

  • custom_audience_bidding_signals: ออบเจ็กต์ JSON ที่แพลตฟอร์มสร้างขึ้น รูปแบบของออบเจ็กต์ JSON นี้คือ

    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 และ name คือสตริงที่ดึงมาจากพร็อพเพอร์ตี้ที่มี ชื่อเดียวกันของกลุ่มเป้าหมายที่กำหนดเองซึ่งเข้าร่วมในการเลือกโฆษณา
    • activation_time และ expiration_time คือเวลาเปิดใช้งานและ เวลาหมดอายุของกลุ่มเป้าหมายที่กำหนดเอง ซึ่งแสดงเป็นวินาทีนับตั้งแต่ Unix Epoch
    • ca_user_bidding_signals คือสตริง JSON ที่ระบุในฟิลด์ userBiddingSignals ของ CustomAudience ในเวลาที่สร้าง
    • trusted_bidding_signals, contextual_signals และ user_signals คือออบเจ็กต์ JSON โดยจะส่งเป็นออบเจ็กต์ที่ว่างเปล่าและจะกรอกข้อมูลใน รุ่นต่อๆ ไป แพลตฟอร์มไม่ได้บังคับใช้รูปแบบของข้อความและเทคโนโลยีโฆษณาเป็นผู้จัดการ

ผลลัพธ์:

  • ad: คือโฆษณาที่ราคาเสนออ้างอิงถึง สคริปต์ได้รับอนุญาตให้แสดงสำเนาของ โฆษณาที่ได้รับพร้อมข้อมูลเมตาที่แตกต่างกัน ระบบคาดว่าพร็อพเพอร์ตี้ render_url ของโฆษณาจะไม่มีการเปลี่ยนแปลง
  • bid: ค่าทศนิยมที่แสดงถึงมูลค่าราคาเสนอสำหรับโฆษณานี้
  • status: ค่าจำนวนเต็มที่อาจเป็นค่าต่อไปนี้
    • 0: เพื่อให้ดำเนินการได้สำเร็จ
    • 1: (หรือค่าที่ไม่ใช่ 0) ในกรณีที่สัญญาณอินพุตใดๆ ไม่ถูกต้อง ในกรณีที่ generate-bid แสดงค่าที่ไม่ใช่ 0 กระบวนการเสนอราคาจะ ถือว่าไม่ถูกต้องสำหรับโฆษณา CA ทั้งหมด

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

พารามิเตอร์อินพุต

  • ad: ดูgenerateBidเอกสารประกอบ
  • bid: มูลค่าราคาเสนอสำหรับโฆษณา

  • ad_selection_config: ออบเจ็กต์ JSON ที่แสดงพารามิเตอร์ AdSelectionConfig ของ selectAds API รูปแบบ คือ

    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 ที่อ่านจากพารามิเตอร์ API sellerSignals AdSelectionConfig

  • trusted_scoring_signal: อ่านจากฟิลด์ adSelectionSignals ในพารามิเตอร์ API ของ AdSelectionConfig

  • contextual_signals, user_signals: ออบเจ็กต์ JSON โดยจะส่งเป็นออบเจ็กต์ว่างและจะมีการกรอกข้อมูลในรุ่นต่อๆ ไป แพลตฟอร์มไม่ได้บังคับใช้รูปแบบของพารามิเตอร์เหล่านี้ และเทคโนโลยีโฆษณาเป็นผู้จัดการ

  • per_buyer_signals: ออบเจ็กต์ JSON ที่อ่านจากperBuyerSignalในพารามิเตอร์ API ของ AdSelectionConfig โดยใช้ผู้ซื้อกลุ่มเป้าหมายที่กำหนดเองปัจจุบันเป็นคีย์ ว่างเปล่าหากแผนที่ไม่มีรายการสำหรับผู้ซื้อที่ระบุ

เอาต์พุต:

  • score: ค่าทศนิยมที่แสดงค่าคะแนนสำหรับโฆษณานี้
  • status: ค่าจำนวนเต็มที่อาจเป็นค่าต่อไปนี้
    • 0: เพื่อให้ดำเนินการสำเร็จ
    • 1: ในกรณีที่ customAudienceSignals ไม่ถูกต้อง
    • 2: ในกรณีที่ AdSelectionConfig ไม่ถูกต้อง
    • 3: ในกรณีที่สัญญาณอื่นๆ ไม่ถูกต้อง
    • ค่าที่ไม่ใช่ 0 จะทำให้กระบวนการล้มเหลว โดยค่า จะกำหนดประเภทของข้อยกเว้นที่เกิดขึ้น

selectOutcome()

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

พารามิเตอร์อินพุต

  • outcomes: ออบเจ็กต์ JSON {"id": id_string, "bid": bid_double}
  • selection_signals: ออบเจ็กต์ JSON ที่ระบุในการกำหนดค่าการประมูล object

เอาต์พุต:

  • status: 0 สำหรับความสำเร็จ ค่าที่ไม่ใช่ 0 สำหรับความล้มเหลว
  • result: ผลลัพธ์อย่างใดอย่างหนึ่งที่ส่งผ่านหรือเป็นค่าว่าง

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

พารามิเตอร์อินพุต

  • ad_selection_config: ดูเอกสารประกอบของ scoreAds
  • render_url: URL การแสดงผลของโฆษณาที่ชนะ
  • bid: ราคาเสนอสำหรับโฆษณาที่ชนะ
  • contextual_signals: ดูเอกสารประกอบของ generateBid

เอาต์พุต:

  • status: 0 สำหรับความสำเร็จ และค่าที่ไม่ใช่ 0 สำหรับความล้มเหลว
  • results: ออบเจ็กต์ JSON ที่มีข้อมูลต่อไปนี้
    • signals_for_buyer: ออบเจ็กต์ JSON ที่ส่งไปยังฟังก์ชัน reportWin
    • reporting_url: URL ที่แพลตฟอร์มใช้เพื่อแจ้งการแสดงผลให้ผู้ซื้อทราบ

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

พารามิเตอร์อินพุต

  • ad_selection_signals, per_buyer_signals: ดูเอกสารประกอบสำหรับ scoreAd
  • signals_for_buyer: ออบเจ็กต์ JSON ที่ reportResult ส่งคืน
  • contextual_signals, custom_audience_signals: ดูเอกสารประกอบสำหรับ generateBid

เอาต์พุต:

  • status: 0 สำหรับความสำเร็จ และค่าที่ไม่ใช่ 0 สำหรับความล้มเหลว
  • results: ออบเจ็กต์ JSON ที่มีข้อมูลต่อไปนี้
    • reporting_url: URL ที่แพลตฟอร์มใช้เพื่อแจ้งการแสดงผลให้ผู้ขายทราบ

registerAdBeacon()

function registerAdBeacon(
  beacons
)

พารามิเตอร์อินพุต

  • beacons: ออบเจ็กต์ที่มีคู่คีย์-ค่าของคีย์การโต้ตอบและ URI การรายงาน รูปแบบคือ

    let beacons = {
  'interaction_key': 'reporting_uri',
  'interaction_key': 'reporting_uri',
  ...
}
    • interaction_key: สตริงที่แสดงถึงเหตุการณ์ แพลตฟอร์มจะใช้ข้อมูลนี้ในภายหลังเมื่อรายงานการโต้ตอบกับเหตุการณ์เพื่อค้นหา reporting_uri ที่ควรได้รับการแจ้งเตือน คีย์นี้ต้องตรงกันระหว่าง สิ่งที่ผู้ซื้อหรือผู้ขายลงทะเบียนกับสิ่งที่ผู้ขายรายงาน
    • reporting_uri: URI สำหรับรับรายงานเหตุการณ์ โดยควรระบุรายละเอียด ของประเภทเหตุการณ์ที่รายงาน ต้องยอมรับคำขอ POST เพื่อจัดการ ข้อมูลที่รายงานพร้อมกับเหตุการณ์

    เช่น

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

URI ที่สร้างไว้ล่วงหน้าสำหรับการเลือกโฆษณา

URI ที่สร้างไว้ล่วงหน้าช่วยให้เทคโนโลยีโฆษณาสามารถกำหนดฟังก์ชัน JavaScript สำหรับตรรกะการตัดสินใจเลือกโฆษณาในคลาส AdSelectionConfig และ AdSelectionFromOutcomesConfig URI ที่สร้างไว้ล่วงหน้าไม่จำเป็นต้องมีการเรียกเครือข่าย เพื่อดาวน์โหลด JavaScript ที่เกี่ยวข้อง เทคโนโลยีโฆษณาสามารถใช้ URI ที่สร้างไว้ล่วงหน้า โดยไม่ต้องตั้งค่าโดเมนที่ลงทะเบียนเพื่อโฮสต์ JavaScript

ระบบจะสร้าง URI ที่กำหนดค่าไว้ล่วงหน้าโดยใช้รูปแบบต่อไปนี้

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

แพลตฟอร์ม Privacy Sandbox มี JavaScript โดยใช้ข้อมูลจาก URI นี้ในรันไทม์

ระบบจะแสดง IllegalArgumentException ในกรณีต่อไปนี้

  • ไม่มีพารามิเตอร์ที่จำเป็นใน URI
  • มีพารามิเตอร์ที่ไม่รู้จักใน URI

กรณีการใช้งานและชื่อ URI ที่สร้างไว้ล่วงหน้าที่รองรับ

กรณีการใช้งานที่ 1: การเลือกโฆษณา

ระบบรองรับ URI ที่สร้างไว้ล่วงหน้าภายใต้กรณีการใช้งาน ad-selection ในโฟลว์ selectAds(AdSelectionConfig)

ชื่อ URI ที่สร้างไว้ล่วงหน้า: highest-bid-wins

URI ที่สร้างไว้ล่วงหน้านี้มี JavaScript ที่เลือกโฆษณาที่มีราคาเสนอสูงสุด หลังจากการเสนอราคา นอกจากนี้ ยังมีฟังก์ชันการรายงานพื้นฐานเพื่อรายงาน render_uri และ bid ของผู้ชนะด้วย

พารามิเตอร์ที่จำเป็น

reportingUrl: URL การรายงานฐานที่มีการกำหนดพารามิเตอร์ด้วย render_uri และ bid ของโฆษณาที่ชนะ

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

การใช้งาน

หาก URL การรายงานพื้นฐานคือ https://www.ssp.com/reporting URI ที่สร้างไว้ล่วงหน้าจะเป็นดังนี้ 

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

กรณีการใช้งาน 2: ad-selection-from-outcomes

URI ที่สร้างไว้ล่วงหน้าภายใต้กรณีการใช้งาน ad-selection-from-outcomes รองรับเวิร์กโฟลว์ selectAds(AdSelectionFromOutcomesConfig)

ชื่อ URI ที่สร้างไว้ล่วงหน้า: waterfall-mediation-truncation

waterfall-mediation-truncation URI ที่สร้างไว้ล่วงหน้ามี JavaScript ที่ ใช้ตรรกะการตัดทอนสื่อกลางแบบ Waterfall โดย JavaScript จะแสดงผล โฆษณาของบุคคลที่หนึ่งหาก bid สูงกว่าหรือเท่ากับ bid floor และ แสดงผล null ในกรณีอื่นๆ

พารามิเตอร์ที่จำเป็น

bidFloor: คีย์ของค่าราคาพื้นฐานของราคาเสนอที่ส่งใน getSelectionSignals() ซึ่งใช้เปรียบเทียบกับโฆษณาของ SDK สื่อกลาง

การใช้งาน

หากสัญญาณการเลือกโฆษณามีลักษณะเป็น {"bid_floor": 10} URI ที่สร้างไว้ล่วงหน้า ที่ได้จะเป็นดังนี้

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

การทดสอบ

เราได้สร้างแอปตัวอย่างใน Kotlin และ Java ไว้ใน GitHub เพื่อช่วยคุณเริ่มต้นใช้งาน Protected Audience API

ข้อกำหนดเบื้องต้น

Protected Audience API ต้องใช้ JavaScript บางอย่างในระหว่างการเลือกโฆษณาและการรายงานการแสดงผล การระบุ JavaScript นี้ในสภาพแวดล้อมการทดสอบทำได้ 2 วิธี ดังนี้

  • เรียกใช้เซิร์ฟเวอร์ที่มีปลายทาง HTTPS ที่จำเป็นซึ่งส่งคืน JavaScript
  • ลบล้างการดึงข้อมูลจากระยะไกลโดยระบุโค้ดที่จำเป็นจากแหล่งที่มาในเครื่อง

ไม่ว่าจะใช้วิธีใดก็ต้องตั้งค่าปลายทาง HTTPS เพื่อจัดการการรายงานการแสดงผล

ปลายทาง HTTPS

หากต้องการทดสอบการเลือกโฆษณาและการรายงานการแสดงผล คุณต้องตั้งค่าปลายทาง HTTPS 7 รายการที่อุปกรณ์ทดสอบหรือโปรแกรมจำลองเข้าถึงได้ ดังนี้

  1. ปลายทางของผู้ซื้อที่แสดง JavaScript ตรรกะการเสนอราคา
  2. ปลายทางที่แสดงสัญญาณการเสนอราคา
  3. ปลายทางของผู้ขายที่แสดง JavaScript ตรรกะการตัดสินใจ
  4. ปลายทางที่แสดงสัญญาณการให้คะแนน
  5. ปลายทางการรายงานการแสดงผลของผู้ซื้อที่ชนะ
  6. ปลายทางการรายงานการแสดงผลของผู้ขาย
  7. ปลายทางเพื่อแสดงข้อมูลอัปเดตรายวันสำหรับกลุ่มเป้าหมายที่กำหนดเอง

ที่เก็บ GitHub มีโค้ด JavaScript พื้นฐานสำหรับการทดสอบเพื่อความสะดวก นอกจากนี้ ยังมีคำจำกัดความบริการ OpenAPI ซึ่งสามารถนำไปใช้กับแพลตฟอร์มจำลองหรือ Microservice ที่รองรับได้ด้วย ดูรายละเอียดเพิ่มเติมได้ที่ README ของโปรเจ็กต์

ลบล้างการดึงข้อมูล JavaScript จากระยะไกล

ฟีเจอร์นี้มีไว้สําหรับใช้ในการทดสอบแบบครบวงจร หากต้องการลบล้างการดึงข้อมูลจากระยะไกล แอปของคุณต้องทำงานในโหมดแก้ไขข้อบกพร่องโดยเปิดใช้ตัวเลือกสำหรับนักพัฒนาแอป

หากต้องการเปิดใช้โหมดแก้ไขข้อบกพร่องสำหรับแอปพลิเคชัน ให้เพิ่มบรรทัดต่อไปนี้ลงในแอตทริบิวต์ application ใน AndroidManifest.xml

<application
  android:debuggable="true">

ดูตัวอย่างวิธีใช้การลบล้างเหล่านี้ได้ในแอปตัวอย่าง Protected Audience API ใน GitHub

คุณต้องเพิ่ม JavaScript ที่กำหนดเองเพื่อจัดการกิจวัตรการเลือกโฆษณา เช่น การเสนอราคา การตัดสินใจให้คะแนน และการรายงาน คุณดูตัวอย่างโค้ด JavaScript พื้นฐานที่จัดการคำขอที่จำเป็นทั้งหมดได้ในที่เก็บ GitHub แอปพลิเคชันตัวอย่างของ Protected Audience API แสดงวิธีอ่านโค้ดจาก ไฟล์นั้นและเตรียมโค้ดเพื่อใช้เป็นการลบล้าง

คุณสามารถลบล้างการดึงข้อมูล JavaScript ฝั่งผู้ขายและฝั่งผู้ซื้อ ได้อย่างอิสระ แต่คุณต้องมีปลายทาง HTTPS เพื่อแสดง JavaScript ที่คุณไม่ได้ระบุการลบล้าง ดูข้อมูลวิธีตั้งค่าเซิร์ฟเวอร์ที่จัดการกรณีเหล่านี้ได้ใน README

คุณจะลบล้างการดึงข้อมูล JavaScript ได้เฉพาะกลุ่มเป้าหมายที่กำหนดเองซึ่ง เป็นของแพ็กเกจของคุณ

ลบล้าง JavaScript ฝั่งผู้ขาย

หากต้องการตั้งค่าการลบล้าง JavaScript ฝั่งผู้ขาย ให้ทำดังนี้ตามที่แสดง ในตัวอย่างโค้ดต่อไปนี้

  1. เริ่มต้นออบเจ็กต์ AdSelectionManager
  2. รับการอ้างอิงถึง TestAdSelectionManager จากออบเจ็กต์ AdSelectionManager
  3. สร้างออบเจ็กต์ AdSelectionConfig
  4. สร้าง AddAdSelectionOverrideRequest ด้วยออบเจ็กต์ AdSelectionConfig และ String ที่แสดงถึง JavaScript ที่คุณต้องการใช้เป็นการลบล้าง
  5. เรียกใช้เมธอด overrideAdSelectionConfigRemoteInfo() แบบอะซิงโครนัสด้วยออบเจ็กต์ AddAdSelectionOverrideRequest และออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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)

Java

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่แต่ละช่องใน AdSelectionConfig แสดงได้ที่ส่วนเรียกใช้การเลือกโฆษณา ความแตกต่างที่สำคัญคือ สามารถตั้งค่า decisionLogicUrl เป็นค่าตัวยึดตำแหน่งได้เนื่องจากระบบจะ ไม่สนใจ

หากต้องการลบล้าง JavaScript ที่ใช้ในระหว่างการเลือกโฆษณา decisionLogicJs ต้องมีลายเซ็นฟังก์ชันที่เหมาะสมฝั่งผู้ขาย ดูตัวอย่างวิธีอ่านไฟล์ JavaScript เป็นสตริงได้ในแอปตัวอย่าง Protected Audience API ใน GitHub

เมธอด overrideAdSelectionConfigRemoteInfo() แบบอะซิงโครนัสใช้ออบเจ็กต์ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

onResult() การเรียกกลับแสดงว่าใช้การลบล้างสำเร็จแล้ว การเรียกใช้ selectAds() ในอนาคตจะใช้ตรรกะการตัดสินใจและการรายงาน ที่คุณส่งเป็นค่าลบล้าง

onError() การเรียกกลับแสดงถึงเงื่อนไข 2 อย่างที่เป็นไปได้

  • หากพยายามลบล้างด้วยอาร์กิวเมนต์ที่ไม่ถูกต้อง AdServiceException จะระบุ IllegalArgumentException เป็นสาเหตุ
  • หากพยายามลบล้างด้วยแอปที่ไม่ได้ทำงานในโหมดแก้ไขข้อบกพร่องโดยเปิดใช้ ตัวเลือกสำหรับนักพัฒนาแอป AdServiceException จะระบุ IllegalStateException เป็นสาเหตุ

รีเซ็ตการลบล้างฝั่งผู้ขาย

ส่วนนี้ถือว่าคุณได้ลบล้าง JavaScript ฝั่งผู้ขายแล้ว และมีข้อมูลอ้างอิงถึง TestAdSelectionManager และ AdSelectionConfig ที่ใช้ในส่วนก่อนหน้า

หากต้องการรีเซ็ตการลบล้างสำหรับ AdSelectionConfigs ทั้งหมด ให้ทำดังนี้

  1. เรียกใช้เมธอด resetAllAdSelectionConfigRemoteOverrides() แบบอะซิงโครนัส ด้วยออบเจ็กต์ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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

Java

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

หลังจากรีเซ็ตการลบล้างฝั่งผู้ขายแล้ว การเรียกไปยัง selectAds() จะใช้ decisionLogicUrl ที่จัดเก็บไว้ใน AdSelectionConfig เพื่อพยายาม ดึงข้อมูล JavaScript ที่จำเป็น

หากการโทรไปยัง resetAllAdSelectionConfigRemoteOverrides() ไม่สำเร็จ OutComeReceiver.onError() การโทรกลับจะให้ AdServiceException หากพยายามนำการลบล้างออกโดยที่แอปไม่ได้ทำงานในโหมดแก้ไขข้อบกพร่อง และเปิดใช้ตัวเลือกสำหรับนักพัฒนาแอป AdServiceException จะระบุ IllegalStateException เป็นสาเหตุ

ลบล้าง JavaScript ฝั่งผู้ซื้อ

  1. ทำตามขั้นตอนเพื่อเข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง
  2. สร้าง AddCustomAudienceOverrideRequest ด้วย buyer และ name ของกลุ่มเป้าหมายที่กําหนดเองที่คุณต้องการลบล้าง นอกเหนือจาก ตรรกะการเสนอราคาและข้อมูลที่คุณต้องการใช้เป็นการลบล้าง
  3. เรียกใช้เมธอด overrideCustomAudienceRemoteInfo() แบบอะซิงโครนัสด้วยออบเจ็กต์ AddCustomAudienceOverrideRequest และออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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)

Java

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

ค่าสำหรับ buyer และ name คือค่าเดียวกันกับที่ใช้สร้าง กลุ่มเป้าหมายที่กำหนดเอง ดูข้อมูลเพิ่มเติมเกี่ยวกับช่องเหล่านี้

นอกจากนี้ คุณยังระบุพารามิเตอร์เพิ่มเติม 2 รายการได้ด้วย ดังนี้

  • biddingLogicJs: JavaScript ที่มีตรรกะของผู้ซื้อซึ่งใช้ ในระหว่างการเลือกโฆษณา ดูลายเซ็นฟังก์ชันที่จำเป็นใน JavaScript นี้
  • trustedBiddingSignals: สัญญาณการเสนอราคาที่จะใช้ในระหว่างการเลือกโฆษณา คุณสามารถเว้นว่างสตริงนี้ไว้เพื่อวัตถุประสงค์ในการทดสอบ

เมธอด overrideCustomAudienceRemoteInfo() แบบอะซิงโครนัสใช้ออบเจ็กต์ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

onResult() การเรียกกลับแสดงว่าใช้การลบล้างสำเร็จแล้ว การเรียกใช้ selectAds() ในภายหลังจะใช้ตรรกะการเสนอราคาและการรายงาน ที่คุณส่งเป็นค่าลบล้าง

การเรียกกลับ onError() แสดงถึงเงื่อนไข 2 อย่างที่เป็นไปได้

  • หากพยายามลบล้างด้วยอาร์กิวเมนต์ที่ไม่ถูกต้อง AdServiceException จะระบุ IllegalArgumentException เป็นสาเหตุ
  • หากพยายามลบล้างด้วยแอปที่ไม่ได้ทำงานในโหมดแก้ไขข้อบกพร่องโดยเปิดใช้ ตัวเลือกสำหรับนักพัฒนาแอป AdServiceException จะระบุ IllegalStateException เป็นสาเหตุ

รีเซ็ตการลบล้างฝั่งผู้ซื้อ

ส่วนนี้ถือว่าคุณได้ลบล้าง JavaScript ฝั่งผู้ซื้อแล้ว และมีข้อมูลอ้างอิงถึง TestCustomAudienceManager ที่ใช้ในส่วนก่อนหน้า

วิธีรีเซ็ตการลบล้างสำหรับกลุ่มเป้าหมายที่กำหนดเองทั้งหมด

  1. เรียกใช้เมธอด resetAllCustomAudienceOverrides() แบบอะซิงโครนัสด้วยออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

Kotlin

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

Java

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

หลังจากรีเซ็ตการลบล้างฝั่งผู้ซื้อแล้ว การเรียกใช้ selectAds() ในครั้งต่อๆ ไปจะใช้ biddingLogicUrl และ trustedBiddingData ที่ จัดเก็บไว้ใน CustomAudience เพื่อพยายามดึงข้อมูล JavaScript ที่จำเป็น

หากการโทรไปยัง resetCustomAudienceRemoteInfoOverride() ไม่สำเร็จ OutComeReceiver.onError() การโทรกลับจะให้ AdServiceException หากพยายามนำการลบล้างออกโดยที่แอปไม่ได้ทำงานในโหมดแก้ไขข้อบกพร่อง และเปิดใช้ตัวเลือกสำหรับนักพัฒนาแอปไว้ AdServiceException จะระบุ IllegalStateException เป็นสาเหตุ

ตั้งค่าเซิร์ฟเวอร์การรายงาน

เมื่อใช้การลบล้างการดึงข้อมูลจากระยะไกล คุณยังคงต้องตั้งค่าเซิร์ฟเวอร์ ที่อุปกรณ์หรือโปรแกรมจำลองสามารถเข้าถึงได้เพื่อตอบสนองต่อเหตุการณ์การรายงาน ปลายทางที่แสดงผล 200 ก็เพียงพอสำหรับการทดสอบแล้ว ที่เก็บ GitHub มี คำจำกัดความของบริการ OpenAPI ซึ่งสามารถนำไปใช้กับแพลตฟอร์มจำลองหรือ ไมโครเซอร์วิสที่รองรับได้ ดูรายละเอียดเพิ่มเติมได้ที่ README ของโปรเจ็กต์

เมื่อมองหานิยาม OpenAPI ให้มองหา reporting-server.json ไฟล์นี้มีปลายทางที่แสดงผล 200 ซึ่งแสดงถึงรหัสการตอบกลับ HTTP ระบบจะใช้ปลายทางนี้ในระหว่าง selectAds() และส่งสัญญาณไปยัง Protected Audience API ว่าการรายงานผลการแสดงผลเสร็จสมบูรณ์แล้ว

ฟังก์ชันการทำงานที่จะทดสอบ

  • ฝึกการเข้าร่วมหรือออกจากกลุ่มเป้าหมาย และการสร้างกลุ่มเป้าหมายที่กำหนดเองตามการดำเนินการก่อนหน้าของผู้ใช้
  • ใช้การเริ่มต้นการเลือกโฆษณาในอุปกรณ์ผ่าน JavaScript ที่โฮสต์จากระยะไกล
  • สังเกตว่าการเชื่อมโยงแอปกับการตั้งค่ากลุ่มเป้าหมายที่กำหนดเองอาจส่งผลต่อผลลัพธ์การเลือกโฆษณาอย่างไร
  • ใช้การรายงานการแสดงผลหลังจากการเลือกโฆษณา

ข้อจำกัด

ตารางต่อไปนี้แสดงข้อจำกัดสำหรับการประมวลผล Protected Audience API ขีดจำกัดที่แสดงอาจมีการเปลี่ยนแปลงตามความคิดเห็น สำหรับความสามารถที่อยู่ระหว่างดำเนินการ โปรดอ่านบันทึกประจำรุ่น

ส่วนประกอบ คำอธิบายขีดจำกัด ค่าขีดจำกัด
กลุ่มเป้าหมายที่กำหนดเอง (CA) จำนวนโฆษณาสูงสุดต่อ CA 100
จำนวน CA สูงสุดต่อแอปพลิเคชัน 1000
จำนวนแอปสูงสุดที่สร้าง CA ได้ 1000
ความล่าช้าสูงสุดในเวลาเปิดใช้งานของ CA จากเวลาที่สร้าง 60 วัน
เวลาหมดอายุสูงสุดของ CA นับจากเวลาเปิดใช้งาน 60 วัน
จำนวน CA สูงสุดในอุปกรณ์ 4000
ขนาดสูงสุดของชื่อ CA 200 ไบต์
ขนาดสูงสุดของ URI การดึงข้อมูลรายวัน 400 ไบต์
ขนาดสูงสุดของ URI ตรรกะการเสนอราคา 400 ไบต์
ขนาดสูงสุดของข้อมูลการเสนอราคาที่เชื่อถือได้ 10 KB
ขนาดสูงสุดของสัญญาณการเสนอราคาของผู้ใช้ 10 KB
อัตราการโทรสูงสุดสำหรับ leaveCustomAudience ต่อผู้ซื้อ 1 ต่อวินาที
อัตราการโทรสูงสุดสำหรับ joinCustomAudience ต่อผู้ซื้อ 1 ต่อวินาที
CA Background Fetch หมดเวลาการเชื่อมต่อ 5 วินาที
หมดเวลาอ่าน HTTP 30 วินาที
ขนาดการดาวน์โหลดทั้งหมดสูงสุด 10 KB
ระยะเวลาสูงสุดของการทำซ้ำการดึงข้อมูล 5 นาที
จำนวน CA สูงสุดที่อัปเดตต่องาน 1000
การเลือกโฆษณา จำนวนผู้ซื้อสูงสุด จะแจ้งภายหลัง
จำนวน CA สูงสุดต่อผู้ซื้อ จะแจ้งภายหลัง
จำนวนโฆษณาสูงสุดในการประมูล จะแจ้งภายหลัง
ระยะหมดเวลาของการเชื่อมต่อเริ่มต้น 5 วินาที
ระยะหมดเวลาในการอ่านการเชื่อมต่อ 5 วินาที
ระยะเวลาดำเนินการสูงสุดโดยรวม AdSelection 10 วินาที
ระยะเวลาดำเนินการสูงสุดของการเสนอราคาต่อ CA ใน AdSelection 5 วินาที
ระยะเวลาดำเนินการสูงสุดของการให้คะแนนใน AdSelection 5 วินาที
ระยะเวลาดำเนินการสูงสุดต่อผู้ซื้อใน AdSelection จะแจ้งภายหลัง
ขนาดสูงสุดของสัญญาณการเลือกโฆษณา/ผู้ขาย/ต่อผู้ซื้อ จะแจ้งภายหลัง
ขนาดสูงสุดของสคริปต์ผู้ขาย/ผู้ซื้อ จะแจ้งภายหลัง
อัตราการโทรสูงสุดสำหรับ selectAds 1 QPS
การรายงานการแสดงผล ระยะเวลาขั้นต่ำก่อนที่จะนำการเลือกโฆษณาออกจากพื้นที่เก็บข้อมูลถาวร 24 ชม.
จำนวนสูงสุดของการเลือกโฆษณาพื้นที่เก็บข้อมูล จะแจ้งภายหลัง
ขนาดสูงสุดของ URL เอาต์พุตการรายงาน จะแจ้งภายหลัง
เวลาสูงสุดสำหรับการรายงานการแสดงผล จะแจ้งภายหลัง
จำนวนครั้งสูงสุดที่ลองใหม่สำหรับการเรียกการแจ้งเตือน จะแจ้งภายหลัง
หมดเวลาการเชื่อมต่อ 5 วินาที
ระยะเวลาดำเนินการโดยรวมสูงสุดสำหรับ reportImpression 2 วินาที
อัตราการโทรสูงสุดสำหรับ reportImpressions 1 QPS
การรายงานเหตุการณ์ จำนวนสูงสุดของบีคอนต่อผู้ซื้อต่อการประมูล 10

จำนวนสูงสุดของบีคอนต่อผู้ขายต่อการประมูล

10

ขนาดสูงสุดของคีย์เหตุการณ์

40 ไบต์

ขนาดสูงสุดของข้อมูลเหตุการณ์

64KB
โฆษณา ขนาดสูงสุดของรายการโฆษณา 10 KB ที่แชร์โดยทุกคน AdData ใน CA เดียวสำหรับบริบท
URLs ความยาวสูงสุดของสตริง URL ที่ใช้เป็นอินพุต จะแจ้งภายหลัง
JavaScript ระยะเวลาดำเนินการสูงสุด 1 วินาทีสำหรับการเสนอราคาและการให้คะแนนสำหรับการรายงานการแสดงผล
หน่วยความจำที่ใช้สูงสุด 10 MB

รายงานข้อบกพร่องและปัญหา

ความคิดเห็นของคุณเป็นส่วนสำคัญของ Privacy Sandbox ใน Android โปรดแจ้งให้เราทราบหากพบปัญหาหรือมีไอเดียในการปรับปรุง Privacy Sandbox ใน Android