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

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

แสดงความคิดเห็น

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

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

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. รวมสิทธิ์ ACCESS_ADSERVICES_CUSTOM_AUDIENCE ในแอปของคุณ ไฟล์ Manifest:

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

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

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

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

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

7. 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

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

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

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

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

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

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

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

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

ชุดค่าผสมของพารามิเตอร์ต่อไปนี้จะระบุค่าแต่ละรายการ CustomAudience ของออบเจ็กต์ในอุปกรณ์

• owner: ชื่อแพ็กเกจของแอปที่เป็นเจ้าของ โดยเป็นการตั้งค่าโดยปริยาย ชื่อแพ็กเกจของแอปผู้โทร
• buyer: ตัวระบุของเครือข่ายโฆษณาของผู้ซื้อซึ่งจัดการโฆษณาสำหรับ กลุ่มเป้าหมาย
• name: ชื่อหรือตัวระบุที่กําหนดเองสําหรับกลุ่มเป้าหมายที่กําหนดเอง

กำลังเรียกใช้ joinCustomAudience() ซ้ำๆ โดยใช้อินสแตนซ์ที่แตกต่างกันของ CustomAudience อัปเดต CustomAudience ที่มีอยู่ด้วย พารามิเตอร์ owner, buyer และ name ที่ตรงกัน เพื่อรักษาความเป็นส่วนตัว ผลลัพธ์ของ API ไม่แยกความแตกต่างระหว่าง "การสร้าง" และ "อัปเดต"

นอกจากนี้ ยังต้องสร้าง CustomAudience ด้วย ได้แก่

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

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

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

ต่อไปนี้คือตัวอย่างการสร้างอินสแตนซ์ออบเจ็กต์ CustomAudience

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

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

จัดการผลลัพธ์ JoinCustomAudience()

เมธอด joinCustomAudience() แบบไม่พร้อมกันใช้ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

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

ต่อไปนี้คือตัวอย่างการจัดการผลลัพธ์ของ joinCustomAudience()

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

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

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

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

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

หากผู้ใช้ไม่ได้มีคุณสมบัติตรงตามเกณฑ์ทางธุรกิจสำหรับ กลุ่มเป้าหมาย แอป หรือ SDK สามารถเรียกใช้ leaveCustomAudience() เพื่อนำข้อความ ผู้ชมจากอุปกรณ์ วิธีนำ CustomAudience ออกตามที่ไม่ซ้ำกัน ให้ทำดังนี้

1. เริ่มต้นออบเจ็กต์ CustomAudienceManager
2. เริ่มต้น LeaveCustomAudienceRequest ด้วยแท็ก buyer และ name ในการเรียนรู้เพิ่มเติมเกี่ยวกับช่องป้อนข้อมูลเหล่านี้ โปรดอ่าน "เข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง"
3. เรียกใช้เมธอด leaveCustomAudience() แบบไม่พร้อมกันด้วยฟังก์ชัน LeaveCustomAudienceRequest ออบเจ็กต์และ Executor ที่เกี่ยวข้องและ ออบเจ็กต์ OutcomeReceiver

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

เมธอด selectAds() ต้องมีอินพุต AdSelectionConfig โดยที่ คุณต้องระบุพารามิเตอร์ที่จำเป็นต่อไปนี้

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

สามารถระบุพารามิเตอร์ต่อไปนี้สำหรับโฆษณาที่กำหนดเองเพิ่มเติม การเลือก:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ขั้นตอนถัดไปคือการตั้งค่าการกรองโฆษณาภายในแอปของผู้เผยแพร่โฆษณา ฝ่ายที่ แสดงโฆษณาภายในแอปผู้เผยแพร่โฆษณา (ส่วนใหญ่เป็น SDK ฝั่งขาย) ต้องเริ่มต้นออบเจ็กต์ AdFilters ด้วยข้อมูลเกี่ยวกับโฆษณา ที่เกี่ยวข้องกับแอปที่ต้องการกรองออก

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

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

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

นอกจากนี้ยังส่งผ่าน AdFilters ในจุดที่เริ่มการสร้าง AdData ใหม่ได้ด้วย ออบเจ็กต์:

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

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

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

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

ตัวกรองความถี่สูงสุดมีองค์ประกอบหลัก 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 ออบเจ็กต์ดังที่แสดงด้านล่าง

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

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

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

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

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

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

เมื่อสร้างออบเจ็กต์ KeyedFrequencyCap แล้ว คุณสามารถส่งรายการดังกล่าวไปยัง AdFilters ออบเจ็กต์

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

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

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

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

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

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

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

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

การกรองโฆษณาตามบริบทโดยไม่ใช้การเรียกเครือข่าย

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

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

วิธีเรียกใช้การเลือกโฆษณาโดยไม่มีการเรียกจากเครือข่าย

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

เครือข่าย 3P

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

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

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

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

SDK แต่ละรายการมีผู้จัดการและลูกค้าบริการเลือกโฆษณาของตนเอง และ การใช้งาน selectAds และ reportImpressions ผู้ให้บริการ SDK สามารถดู ส่วนวิธีเรียกใช้การเลือกโฆษณาสำหรับการประมูลในอุปกรณ์หรือ B&A คำอธิบายสำหรับการประมูล B&A ทำตามวิธีรายงานโฆษณา การแสดงผล (หลังจากการรายงานการแสดงผล SSP รายการเดียวของ การรายงาน

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

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

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

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

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

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

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

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

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

สร้าง AdSelectionFromผลลัพธ์sConfig

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

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

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

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

    return adSelectionClient.selectAds(config){}
}

การลบล้างเมธอด selectAds() สําหรับสื่อกลาง Waterfall จำเป็นต้องมี AdSelectionFromOutcomesConfig โดยคุณต้องระบุข้อมูลต่อไปนี้ พารามิเตอร์ที่จำเป็นต่อไปนี้

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

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

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

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

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

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

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

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

การแสดงโฆษณาสื่อกลางตามลำดับขั้น (Waterfall Mediation) แบบออร์เคสตรา

ต่อไปนี้คือลำดับการดำเนินการสำหรับการทำงานผ่านสื่อกลาง ขั้นตอนได้

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

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

เริ่มต้น ReportImpressionRequest ด้วยสิ่งต่อไปนี้ ได้แก่

• รหัสการเลือกโฆษณา: รหัสเฉพาะสำหรับผู้ใช้อุปกรณ์ที่ระบุ สำเร็จในการเลือกโฆษณา
• การกำหนดค่าการเลือกโฆษณา: การกำหนดค่าเดียวกับที่ใช้ใน selectAds() ที่ระบุโดยรหัสการเลือกโฆษณาที่ให้ไว้

เมธอด reportImpression() แบบไม่พร้อมกันใช้ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

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

การรายงานการแสดงผลสื่อกลาง Waterfall

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

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

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

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

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

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

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

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

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

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

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

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

การรายงานการแสดงผลเพื่อให้ได้ผลลัพธ์ดีที่สุด

เมธอด reportImpression() ได้รับการออกแบบมาเพื่อใช้ การรายงาน

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

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

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

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

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

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

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

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

การรายงานการโต้ตอบที่ดีที่สุด

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 ที่แสดงผลควรมีฟังก์ชันต่อไปนี้

• generateBid()
• reportWin()

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

• scoreAd()
• reportResult()

generateBid()

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

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

• 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) ในกรณีที่สัญญาณอินพุตไม่ถูกต้อง ใน ในกรณีที่ "สร้างราคาเสนอ" แสดงค่าที่ไม่ใช่ 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 พารามิเตอร์ API AdSelectionConfig

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

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

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

เอาต์พุต:

• 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 ที่ระบุในการกำหนดค่าการประมูล ออบเจ็กต์

เอาต์พุต:

• 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

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

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

ระบบรองรับ URI ที่สร้างไว้ล่วงหน้าภายใต้ Use Case 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 URL ที่สร้างไว้ล่วงหน้า URI จะเป็นดังนี้

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

กรณีการใช้งานที่ 2: การเลือกโฆษณาจากแหล่งที่มา

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

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

URI ที่สร้างไว้ล่วงหน้า waterfall-mediation-truncation มี JavaScript ที่ ใช้ตรรกะการตัดทอนการแสดงโฆษณาสื่อกลางตามลำดับขั้น (Waterfall Mediation) ที่ที่ 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`

การทดสอบ

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

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

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

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

ทั้ง 2 วิธีการนี้ต้องมีการตั้งค่าปลายทาง HTTPS เพื่อรองรับการแสดงผล การรายงาน

ปลายทาง HTTPS

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

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

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

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

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

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

<application
  android:debuggable="true">

สำหรับตัวอย่างวิธีใช้การลบล้าง โปรดดูที่แท็ก แอปตัวอย่าง 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 ออบเจ็กต์

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

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

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

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

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

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

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

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

ดูส่วนเรียกใช้การเลือกโฆษณาสำหรับข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่ ช่องในคอลัมน์ 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 ที่เกี่ยวข้อง

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

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

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

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

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

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

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

// Join custom audience

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

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

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

// Join custom audience

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

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

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

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

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

เมธอด overrideCustomAudienceRemoteInfo() แบบไม่พร้อมกันใช้เมธอด OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ข้อจำกัด

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

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

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