รายงานเกี่ยวกับผลการประมูล Protected Audience API

คำแนะนำสำหรับผู้ขายและผู้ซื้อในการสร้างรายงานการประมูล Protected Audience API

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

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

หากคุณไม่ใช่ผู้พัฒนาแอป ดูภาพรวมของ Protected Audience API

Protected Audience API รายงานอะไร

รายงาน Protected Audience API ที่พร้อมใช้งานมี 2 รายงาน ได้แก่

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

แผนระยะยาวคือการอนุญาตให้เบราว์เซอร์รายงานผลการประมูลสำหรับผู้ขายและผู้ซื้อด้วย Private Aggregation API ในฐานะกลไกการรายงานระดับเหตุการณ์ชั่วคราว โค้ดที่ใช้ reportResult() สำหรับผู้ขาย และ reportWin() สำหรับผู้เสนอราคาที่ชนะ สามารถเรียกใช้ฟังก์ชัน sendReportTo() ได้ ฟังก์ชันนี้รับอาร์กิวเมนต์เดียวคือสตริง ซึ่งแสดง URL ที่ดึงข้อมูลหลังจากที่การประมูลเสร็จสมบูรณ์ ซึ่งจะเข้ารหัส ข้อมูลระดับเหตุการณ์ที่จะรายงาน

ฟังก์ชัน API

ผู้ขาย: reportResult()

JavaScript ของผู้ขายที่ระบุใน decisionLogicUrl (ซึ่งระบุ scoreAd() ด้วย) สามารถมีฟังก์ชัน reportResult() เพื่อรายงานผลการประมูลได้

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

อาร์กิวเมนต์ที่ส่งไปยังฟังก์ชันนี้มีดังนี้

auctionConfig

ออบเจ็กต์การกำหนดค่าการประมูลที่ส่งไปยัง navigator.runAdAuction()

browserSignals

ออบเจ็กต์ที่เบราว์เซอร์สร้างขึ้นซึ่งให้ข้อมูลเกี่ยวกับการประมูล เช่น

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

ระบบจะใช้ค่าที่ฟังก์ชันนี้ส่งคืนเป็นอาร์กิวเมนต์ sellerSignals สำหรับฟังก์ชัน reportWin() ของผู้เสนอราคาที่ชนะ

ผู้ซื้อ: reportWin()

JavaScript ของผู้เสนอราคาที่ชนะ (ซึ่งมี generateBid() ด้วย) สามารถ มีฟังก์ชัน reportWin() เพื่อรายงานผลการประมูล

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

อาร์กิวเมนต์ที่ส่งไปยังฟังก์ชันนี้มีดังนี้

auctionSignals และ perBuyerSignals

ค่าเดียวกันที่ส่งไปยัง generateBid() สำหรับผู้เสนอราคาที่ชนะ

sellerSignals

ค่าที่ส่งคืนของ reportResult() ซึ่งช่วยให้ผู้ขายมีโอกาสส่งข้อมูลไปยังผู้ซื้อ

browserSignals

ออบเจ็กต์ที่เบราว์เซอร์สร้างขึ้นซึ่งให้ข้อมูลเกี่ยวกับการประมูล เช่น

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

การติดตั้งใช้งานการรายงานชั่วคราว

Chrome มี 2 วิธีในการรายงานการประมูลที่พร้อมใช้งานชั่วคราว ดังนี้

• forDebuggingOnly.reportAdAuctionLoss()
• forDebuggingOnly.reportAdAuctionWin()

แต่ละวิธีจะรับอาร์กิวเมนต์เดียว ซึ่งคือ URL ที่จะดึงข้อมูลหลังจากที่การประมูลเสร็จสมบูรณ์ โดยเรียกใช้ได้หลายครั้งทั้งใน scoreAd() และ generateBid() โดยมีอาร์กิวเมนต์ URL ที่แตกต่างกัน

Chrome จะส่งรายงานการสูญเสีย/ชนะการแก้ไขข้อบกพร่องเมื่อการประมูลทำงานจนเสร็จสมบูรณ์เท่านั้น หากมีการยกเลิกการประมูล (เช่น เนื่องจากการนำทางใหม่) ระบบจะไม่สร้างรายงาน

โดยค่าเริ่มต้น วิธีการเหล่านี้จะพร้อมใช้งานใน Chrome เมื่อคุณเปิดใช้ Ad Privacy API ทั้งหมดในส่วนchrome://settings/adPrivacy หากคุณเรียกใช้ Chrome ด้วย Flag บรรทัดคำสั่งเพื่อเปิดใช้ Protected Audience API คุณจะต้องเปิดใช้เมธอดอย่างชัดเจนโดยใส่ Flag BiddingAndScoringDebugReportingAPI หากไม่ได้เปิดใช้ฟีเจอร์นี้ วิธีการดังกล่าวจะยังคงพร้อมใช้งานแต่จะไม่มีผลใดๆ

การอ้างอิง API ทั้งหมดของ Protected Audience API

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.