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

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

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 รุ่นเบต้าจาก 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() callback เมื่อการเรียก 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 ที่คอมไพล์ไว้ล่วงหน้าซึ่งไม่รองรับหรือมีรูปแบบไม่ถูกต้อง
  • ผู้ซื้อกลุ่มเป้าหมายที่กำหนดเอง: รายการตัวระบุทั้งหมดสำหรับเครือข่ายโฆษณาของผู้ซื้อที่ seller อนุญาตให้เข้าร่วมในกระบวนการเลือกโฆษณา ตัวระบุผู้ซื้อเหล่านี้สอดคล้องกับกลุ่มเป้าหมายที่กําหนดเอง CustomAudience.getBuyer() กลุ่มที่เข้าร่วม

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

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

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

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

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

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

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

Protected Audience สามารถรวมโฆษณาตามบริบทไว้ในการประมูลที่มีการป้องกันได้ คุณต้องเลือกโฆษณาตามบริบทในเซิร์ฟเวอร์เทคโนโลยีโฆษณาและส่งกลับไปยังอุปกรณ์นอก Protected Audience API จากนั้นจะรวมโฆษณาตามบริบทในการประมูลได้โดยใช้ AdSelectionConfig เมื่อถึงจุดนี้ โฆษณาจะทํางานเหมือนกับโฆษณาในอุปกรณ์ รวมถึงมีสิทธิ์ใช้การกรองโฆษณาเชิงลบ เมื่อการประมูลกลุ่มเป้าหมายที่ได้รับการปกป้องเสร็จสมบูรณ์แล้ว คุณจะต้องเรียกใช้ 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 จะอัปเดตเหตุการณ์ Conversion ที่เกิดขึ้นโดยอัตโนมัติ และนักพัฒนาแอปเรียกใช้โดยตรงไม่ได้ ข้อมูลการได้ผู้ใช้ใหม่จะแสดงต่อโฆษณาภายในกลุ่มเป้าหมายที่กําหนดเองเท่านั้น
  • การแสดงผล: ผู้เรียกใช้บนอุปกรณ์ (SSP หรือ MMP) ใช้ updateAdCounterHistogram() เพื่อเรียกเหตุการณ์การแสดงผล ณ จุดในโค้ดที่เลือกแยกต่างหากจาก reportImpression เหตุการณ์การแสดงผลจะแสดงในโฆษณาทั้งหมดของ 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);

เรียกใช้การแสดงโฆษณาสื่อกลางตามลำดับขั้น

การแสดงโฆษณาสื่อกลางตามลำดับขั้นกำหนดให้เครือข่ายสื่อกลาง SDK ของบุคคลที่หนึ่งต้องจัดการ SDK ของบุคคลที่สามหลายรายการ (เครือข่ายบุคคลที่สาม) สื่อกลาง Waterfall จะทํางานในลักษณะเดียวกัน ไม่ว่าการประมูลจะเกิดขึ้นในอุปกรณ์หรือทํางานในบริการเสนอราคาและประมูล (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 เช่นเดียวกับเครือข่ายของบุคคลที่สาม ดูข้อมูลเพิ่มเติมได้ที่ส่วนวิธีเรียกใช้การเลือกโฆษณาและวิธีรายงานการแสดงโฆษณา

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

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

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

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

SDK สื่อกลางสามารถวางตัวเองในเชนสื่อกลางตาม eCPM จริงของราคาเสนอโฆษณาจากบุคคลที่หนึ่ง ใน Protected Audience API การเสนอราคาโฆษณาจะเป็นแบบทึบ SDK สื่อกลางควรใช้ AdSelectionFromOutcomesConfig เพื่อให้เปรียบเทียบราคาเสนอของโฆษณา 1P หนึ่งๆ กับราคาเสนอขั้นต่ำของเครือข่ายบุคคลที่สามถัดไปในเชนได้ หากราคาเสนอของ 1P สูงกว่าราคาเสนอขั้นต่ำ แสดงว่า 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() สําหรับสื่อกลาง Waterfall ต้องใช้อินพุต AdSelectionFromOutcomesConfig โดยคุณต้องระบุพารามิเตอร์ที่จําเป็นต่อไปนี้

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

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

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

จัดระเบียบการแสดงโฆษณาสื่อกลางตามลำดับขั้น

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

  1. เรียกใช้การเลือกโฆษณาของบุคคลที่หนึ่ง
  2. วนเชนสื่อกลาง ทําดังนี้สําหรับเครือข่ายของบุคคลที่สามแต่ละเครือข่าย
    1. สร้าง AdSelectionFromOutcomeConfig ซึ่งรวมถึง outcomeId ของ 1P และราคาเสนอขั้นต่ำของ 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 การรายงานการแสดงผลและตั้งเวลาคําขอไว้หรือไม่
  • ฟังก์ชัน Callback ของ onError() จะระบุเงื่อนไขที่เป็นไปได้ดังต่อไปนี้
    • หากการเรียกเริ่มต้นด้วยอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง 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 การรายงานการแสดงผล
  • เรียกใช้ฟังก์ชัน JavaScript reportWin() ซึ่งคาดว่าจะแสดงผล URL การรายงานการแสดงผลของผู้ซื้อ

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

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

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

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

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

Report Interaction API จะส่งคําขอ HTTPS POST ไปยังปลายทางที่ระบุโดยแพลตฟอร์มฝั่งขายและแพลตฟอร์มฝั่งซื้อที่ชนะ กลุ่มเป้าหมายที่ได้รับการคุ้มครองจะจับคู่คีย์การโต้ตอบกับ 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"
}

    where:

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

ผลลัพธ์:

  • ad: คือโฆษณาที่ราคาเสนออ้างอิงถึง สคริปต์ได้รับอนุญาตให้แสดงโฆษณาที่ได้รับพร้อมข้อมูลเมตาอื่น ระบบคาดว่าพร็อพเพอร์ตี้ render_url ของโฆษณาจะไม่เปลี่ยนแปลง
  • bid: ค่าประเภท float ที่แสดงถึงมูลค่าราคาเสนอสําหรับโฆษณานี้
  • 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 ที่อ่านจากพารามิเตอร์ sellerSignals AdSelectionConfig API

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

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

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

เอาต์พุต:

  • score: ค่า float ที่แสดงค่าคะแนนของโฆษณานี้
  • 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: ผลลัพธ์ที่ส่งผ่านหรือค่า 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 }
   };
}

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

  • 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: ad-selection

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

ชื่อ 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

URI ที่สร้างไว้ล่วงหน้า waterfall-mediation-truncation มี 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 จากระยะไกล

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

หากต้องการเปิดใช้โหมดแก้ไขข้อบกพร่องสําหรับแอปพลิเคชัน ให้เพิ่มบรรทัดต่อไปนี้ลงในแอตทริบิวต์แอปพลิเคชันใน 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 ที่มีผู้ซื้อและชื่อของกลุ่มเป้าหมายที่กําหนดเองที่คุณต้องลบล้าง นอกเหนือจากตรรกะการเสนอราคาและข้อมูลที่คุณต้องการใช้เป็นการลบล้าง
  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 100
จำนวน CA สูงสุดต่อใบสมัคร 1000
จำนวนแอปสูงสุดที่สร้าง CA ได้ 1000
ความล่าช้าสูงสุดของเวลาเปิดใช้งาน CA จากเวลาที่สร้าง 60 วัน
ระยะเวลาหมดอายุสูงสุดของ CA นับจากเวลาที่เปิดใช้งาน 60 วัน
จำนวน CA สูงสุดในอุปกรณ์ 4000
ขนาดสูงสุดของชื่อ CA 200 ไบต์
ขนาดสูงสุดของ URI การดึงข้อมูลรายวัน 400 ไบต์
ขนาดสูงสุดของ URI ของตรรกะการเสนอราคา 400 ไบต์
ขนาดสูงสุดของข้อมูลการเสนอราคาที่เชื่อถือได้ 10 KB
ขนาดสูงสุดของสัญญาณการเสนอราคาของผู้ใช้ 10 KB
อัตราการเรียกใช้สูงสุดสำหรับ leaveCustomAudience ต่อผู้ซื้อ 1 ราย 1 ครั้งต่อวินาที
อัตราการเรียกใช้สูงสุดสำหรับ joinCustomAudience ต่อผู้ซื้อ 1 ราย 1 ครั้งต่อวินาที
การดึงข้อมูลในเบื้องหลังของแคนาดา หมดเวลาการเชื่อมต่อ 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