การรายงานการประมูลของ Protected Audience API

วัดข้อมูลและผลลัพธ์การประมูลที่ใช้ Protected Audience API

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

หากต้องการรายงานเมตริกสําคัญที่คุณรวบรวมจากการประมูลเพื่อแสดงโฆษณา Protected Audience API จะทํางานร่วมกับ

• Private Aggregation ซึ่งรวบรวมสัญญาณและผลลัพธ์การประมูลเพื่อสร้างรายงานสรุป
• Ads Reporting API สำหรับ Fenced Frame และ iframe ซึ่งเป็นช่องทางภายในเฟรมเพื่อสื่อสารกับ Worklet ของ Protected Audience API API อนุญาตให้เชื่อมโยงข้อมูลระดับเหตุการณ์กับสัญญาณการประมูล การรายงานระดับเหตุการณ์ของ Ads Reporting API เป็นกลไกการเปลี่ยนผ่านจนกว่าจะมีการออกแบบกลไกการรายงานที่เป็นส่วนตัวมากขึ้น
• การรายงานการระบุแหล่งที่มา ซึ่งช่วยให้คุณเชื่อมโยงข้อมูล Conversion กับสัญญาณการประมูลได้
• Shared Storage ซึ่งช่วยให้คุณเขียนสัญญาณการประมูลไปยังพื้นที่เก็บข้อมูลแบบข้ามต้นทาง จากนั้นจะช่วยให้คุณรายงานข้อมูลดังกล่าวได้ในภายหลังโดยใช้ Private Aggregation

ภาพรวมการรายงาน Protected Audience API

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

ในระหว่างเวลาการประมูล คุณสามารถรายงานข้อมูลการประมูลได้โดยใช้ Worklet การรายงาน ในระหว่างเวลาในการแสดงผล คุณสามารถรายงานข้อมูลการมีส่วนร่วมจาก iframe หรือ Fenced Frame ได้ ในระหว่างเวลาที่เกิด Conversion คุณสามารถรายงานข้อมูลการระบุแหล่งที่มาจากหน้าปลายทางได้โดยใช้ Attribution Reporting API

สถานที่ตั้งที่รายงาน

ในการประมูล ผู้ซื้อจะรายงานสัญญาณที่มีอยู่ใน Worklet generateBid() และ reportWin() ได้ ส่วนผู้ขายจะรายงานสัญญาณที่มีอยู่ใน scoreAd() และ reportResult() ได้ นอกเหนือจากการประมูลแล้ว ผู้ซื้อและผู้ขายสามารถรายงานข้อมูลจากเฟรมที่แสดงโฆษณา และจากเว็บไซต์ที่เกิด Conversion ได้

ในช่วงระยะเวลาแต่ละช่วงที่ระบุไว้ ผู้ซื้อและผู้ขายจะมีสิทธิ์เข้าถึง API การรายงานต่างๆ ที่พร้อมใช้งานเพื่อรายงานข้อมูล เช่น สัญญาณการประมูล ข้อมูลระดับเหตุการณ์ และข้อมูล Conversion

ข้อมูลที่ใช้ได้ในการประมูลที่ใช้ Protected Audience API

ข้อมูลต่อไปนี้พร้อมให้รายงานจาก Worklet ของ Protected Audience API ในระหว่างการประมูล

สัญญาณ

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

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

ข้อมูลอื่นๆ ที่พร้อมใช้งาน

• ข้อมูลผลลัพธ์ที่เกี่ยวข้องกับข้อมูลการชนะและการแพ้ในการประมูล เช่น ราคาเสนอที่ชนะและเหตุผลในการปฏิเสธราคาเสนอ
• ข้อมูลประสิทธิภาพที่มีข้อมูลเวลาในการตอบสนอง เช่น ระยะเวลาที่ใช้ในการดึงและเรียกใช้ Worklet การเสนอราคา

ข้อมูลที่ใช้ได้นอกการประมูลที่ใช้ Protected Audience API

นอกเหนือจากการประมูลที่ใช้ Protected Audience API แล้ว ยังมีช่วงเวลา 2 ช่วงที่ข้อมูลพร้อมให้รายงาน

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

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

การรายงานระดับเหตุการณ์

รายงานระดับเหตุการณ์จะแสดงรายละเอียดข้อมูลจากเหตุการณ์อย่างน้อย 1 รายการ เหตุการณ์อาจเป็นการชนะการประมูล การแสดงโฆษณา หรือ Conversion จนถึงอย่างน้อยปี 2026 การรายงานการชนะการประมูลระดับเหตุการณ์จะยังคงมีอยู่ ไม่จำเป็นต้องใช้เฟรมที่จำกัดเพื่อแสดงโฆษณา Protected Audience และสามารถใช้ iframe ที่มีการเข้าถึงเครือข่ายแบบไม่จำกัดสำหรับการรายงานระดับเหตุการณ์ได้ นอกจากนี้ Ads Reporting API ยังพร้อมใช้งานในเฟรมที่จำกัดและ iframe เพื่อให้คุณเชื่อมโยงข้อมูลการประมูลและ Conversion กับข้อมูลระดับเหตุการณ์จากเฟรมได้ ซึ่งออกแบบมาเพื่อให้ระบบนิเวศมีเส้นทางการย้ายข้อมูลที่ง่ายขึ้น เนื่องจากคุณจะใช้โครงสร้างพื้นฐานการรายงานที่มีอยู่ต่อไปได้จนถึงอย่างน้อยปี 2026 ในขณะที่ย้ายข้อมูลระบบไปยัง Protected Audience

การรายงานการชนะการประมูลระดับเหตุการณ์ด้วย sendReportTo()

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

ตัวอย่างเช่น ผู้ซื้อสามารถรายงานจำนวนราคาเสนอที่ชนะจาก reportWin() Worklet เพื่อวัตถุประสงค์ในการเรียกเก็บเงินได้ดังนี้

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

ฟังก์ชัน sendReportTo() สามารถใช้เพื่อสร้างรายงานการชนะสำหรับผู้ขายเมื่อเรียกใช้จาก reportResult() และรายงานการชนะสำหรับผู้ซื้อเมื่อเรียกใช้จาก reportWin() ฟังก์ชัน sendReportTo() จะพร้อมให้บริการจนถึงปี 2026 เป็นอย่างน้อย

รายงานการมีส่วนร่วม

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

คุณใช้ฟังก์ชัน sendReportTo() ที่อธิบายไว้ข้างต้นเพื่อเชื่อมโยงข้อมูลการประมูลกับข้อมูลระดับเหตุการณ์จาก iframe ได้ แต่จะใช้กับ Fenced Frame ไม่ได้เนื่องจากส่งรหัสที่ไม่ซ้ำจากผู้ฝังไม่ได้เนื่องจากการสื่อสารระหว่างผู้ฝังกับ Fenced Frame มีข้อจำกัด หากต้องการเชื่อมโยงข้อมูลการประมูลกับข้อมูลระดับเหตุการณ์จากโฆษณาในเฟรมที่จำกัด Ads Reporting API จะช่วยคุณได้

Ads Reporting API สำหรับ Fenced Frame และ iframe

Ads Reporting API สำหรับเฟรมที่จำกัดและ iframe มีกลไกให้คุณเชื่อมโยงข้อมูลระดับเหตุการณ์ของผู้ใช้จากเฟรมโฆษณากับสัญญาณในการประมูลที่ใช้ Protected Audience

ใน Worklet การรายงาน Protected Audience API คุณสามารถลงทะเบียนบีคอนโฆษณาด้วยฟังก์ชัน registerAdBeacon() และส่ง URL การรายงานพร้อมสัญญาณที่เพิ่มเป็นพารามิเตอร์การค้นหา นอกจากนี้ คุณยังระบุเหตุการณ์ที่กําหนดเองที่ต้องการเชื่อมโยงกับ URL การรายงานได้ด้วย จากนั้นในภายหลังเมื่อโฆษณาแสดงในกรอบที่จำกัด คุณจะทริกเกอร์เหตุการณ์ที่กำหนดเองได้โดยเรียกใช้ฟังก์ชัน window.fence.reportEvent() คุณเพิ่มข้อมูลที่มีอยู่ในเฟรมที่จำกัดได้เป็นเพย์โหลด

ฟังก์ชัน registerAdBeacon() ใช้ได้เฉพาะในฟังก์ชันการรายงานเท่านั้น และใช้ไม่ได้ในตรรกะการเสนอราคาของผู้ซื้อและตรรกะการให้คะแนนของผู้ขาย

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

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

นอกจากนี้ Fenced Frames Ads Reporting API จะยังคงพร้อมใช้งานต่อไปจนถึงปี 2026 เป็นอย่างน้อยด้วยเหตุผลเดียวกันกับการรายงานการชนะ

ดูข้อมูลแบบเจาะลึกได้ที่คำอธิบาย

การเข้าถึงเครือข่ายแบบไม่จำกัด

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

เราจะจำกัดการเข้าถึงเครือข่ายในอนาคต

รายงานการระบุแหล่งที่มา

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

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

กลไกการเปลี่ยนผ่าน

เมื่อลงทะเบียนบีคอนโฆษณา คุณสามารถใช้คีย์เวิร์ด reserved.top_navigation ซึ่งจะเพิ่มส่วนหัว Attribution-Reporting-Eligible โดยอัตโนมัติเพื่อให้บีคอนมีสิทธิ์ลงทะเบียนเป็นแหล่งที่มาของการระบุแหล่งที่มา

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

หากต้องการแนบข้อมูลระดับเหตุการณ์กับบีคอนที่คุณลงทะเบียนไว้ ให้เรียกใช้ setReportEventDataForAutomaticBeacons() จากเฟรมที่จำกัดด้วยรั้วทางภูมิศาสตร์พร้อมเพย์โหลดของเหตุการณ์

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

ดูข้อมูลเพิ่มเติมได้ที่ส่วนการรายงานการระบุแหล่งที่มาของคำอธิบาย Ads Reporting API

ตัวอย่างการรายงานการมีส่วนร่วมและ Conversion

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

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

เวิร์กโฟลว์

1. ก่อนที่การประมูลจะเริ่มขึ้น ผู้ซื้อจะส่งรหัสที่ไม่ซ้ำกันไปยังผู้ขายเป็นส่วนหนึ่งของการตอบกลับราคาเสนอแบบเรียลไทม์ ("RTB") แบบเป็นโปรแกรม คุณตั้งค่ารหัสเป็นตัวแปรได้ เช่น auctionId ระบบจะส่งรหัสเป็น perBuyerSignals ใน auctionConfig และรหัสจะพร้อมใช้งานในเวิร์กเล็ตของผู้ซื้อ
2. ในระหว่างเวลาการประมูล ผู้ซื้อสามารถลงทะเบียนบีคอนโฆษณาให้ทริกเกอร์ในระหว่างเวลาการแสดงโฆษณาและเวลา Conversion (registerAdBeacon())
   1. หากต้องการเชื่อมโยงสัญญาณการประมูลสําหรับเหตุการณ์เฟรมโฆษณา ให้ตั้งค่า auctionId เป็นพารามิเตอร์การค้นหาของ URL บีคอน
   2. หากต้องการเชื่อมโยงสัญญาณการประมูลสําหรับเหตุการณ์ Conversion ให้ตั้งค่า auctionId ใน URL ของบีคอน
3. ในระหว่างเวลาการแสดงโฆษณา ระบบจะทริกเกอร์หรือเพิ่มประสิทธิภาพบีคอนที่คุณลงทะเบียนไว้ในระหว่างเวลาการประมูลด้วยข้อมูลระดับเหตุการณ์
   1. ทริกเกอร์เหตุการณ์เฟรมด้วย reportEvent() และส่งข้อมูลระดับเหตุการณ์
   2. เพิ่มเพย์โหลดระดับเหตุการณ์ลงในบีคอนการระบุแหล่งที่มาด้วย setReportEventDataForAutomaticBeacons()
   3. ลงทะเบียนโฆษณากับ Attribution Reporting API โดยตอบกลับคำขอ Beacon โฆษณาด้วยส่วนหัว Attribution-Reporting-Register-Source
4. ในระหว่างเวลา Conversion คุณสามารถทริกเกอร์แหล่งที่มาที่คุณลงทะเบียนไว้ในระหว่างเวลาการประมูลได้

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

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

การรวบรวมข้อมูล Protected Audience

Private Aggregation API เป็นกลไกที่ใช้ในการรายงานข้อมูล Protected Audience เพื่อสร้างรายงานสรุป ซึ่งเป็นรายงานรวมที่มีการเพิ่ม Noise ของข้อมูลที่รวบรวมไว้ในที่เก็บข้อมูล โดย Bucket จะแสดงด้วยคีย์การรวม และสามารถเข้ารหัสข้อมูลบางอย่างลงในคีย์ได้

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ API ได้ที่บทความการรวมข้อมูลแบบส่วนตัว

การรวบรวมสัญญาณการประมูล

คุณสามารถรวบรวมสัญญาณที่มีอยู่ใน Worklet ไปยังเซิร์ฟเวอร์ได้โดยใช้ Private Aggregation สําหรับการรวบรวมสัญญาณ คุณสามารถใช้วิธี privateAggregation.contributeToHistogram() ที่มีอยู่ใน Worklet การเสนอราคาของผู้ซื้อ, Worklet การให้คะแนนผู้ขาย และ Worklet การรายงานของผู้ซื้อ/ผู้ขาย

ในตัวอย่างนี้ ระบบจะรวบรวมราคาเสนอที่ชนะลงในที่เก็บข้อมูลของเจ้าของกลุ่มความสนใจ

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

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

การรวมสัญญาณการประมูลกับข้อมูลเหตุการณ์

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

หากต้องการรวบรวมสัญญาณการประมูลตามเหตุการณ์ คุณสามารถใช้ privateAggregation.contributeToHistogramOnEvent(eventType, contribution) ซึ่งรับสตริงที่ระบุประเภทเหตุการณ์และการมีส่วนร่วมที่จะรายงานเมื่อมีการทริกเกอร์เหตุการณ์นั้น คุณเรียกใช้เมธอดด้วยประเภทเหตุการณ์ที่กำหนดเองได้ จากนั้นเรียกใช้ window.fence.reportEvent(eventType) จากเฟรมโฆษณาเพื่อทริกเกอร์ให้ส่งรายงาน

สมมติว่าคุณต้องการวัดจำนวนคลิกที่โฆษณาสำหรับแคมเปญได้รับ

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

ในฟังก์ชันการสร้างราคาเสนอ คุณสามารถกําหนดกลุ่มเป็นชุดค่าผสมของรหัสแคมเปญและเหตุการณ์คลิก จากนั้นเพิ่มค่าสําหรับกลุ่มนั้น 1 ทุกครั้งที่ระบบทริกเกอร์เหตุการณ์

// Ad frame
window.fence.reportEvent('click');

จากนั้นในภายหลัง คุณสามารถทริกเกอร์การส่งรายงานจากกรอบโฆษณาได้โดยการเรียกใช้ reportEvent(eventType)

ดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกใช้การมีส่วนร่วมของ Private Aggregation จากเฟรมจากคำอธิบาย

การรายงานผลลัพธ์และประสิทธิภาพของการประมูล

นอกจากนี้ คุณยังรวบรวมผลการประมูลได้เมื่อทริกเกอร์โดยเหตุการณ์ชนะหรือแพ้การประมูลด้วย contributeToHistogramOnEvent(eventType, contribution) เมื่อส่งคีย์เวิร์ดประเภทเหตุการณ์ที่สงวนไว้ (reserved.win, reserved.loss และ reserved.always)

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

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

การรายงานผลการประมูล

มาดูตัวอย่างที่คุณแพ้การประมูลและต้องการทราบว่าราคาเสนอของคุณแตกต่างจากราคาที่ชนะการประมูลมากน้อยเพียงใด

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

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

เมื่อส่งรายงาน ค่าที่รายงานจริงจะเป็นค่าที่ปรับขนาดแล้วbaseValueซึ่งoffsetจะปรับค่า ดูข้อมูลเพิ่มเติมได้ที่คำอธิบาย

การรายงานประสิทธิภาพ

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

ดูข้อมูลเพิ่มเติมได้ที่คำอธิบาย

การจัดเก็บสัญญาณการประมูลใน Shared Storage

พื้นที่เก็บข้อมูลที่ใช้ร่วมกันคือพื้นที่เก็บข้อมูลแบบข้ามต้นทางที่ไม่ได้แบ่งพาร์ติชันซึ่งคุณเขียนได้อย่างอิสระ แต่จะมีการป้องกันเมื่ออ่านและประมวลผลค่าที่จัดเก็บไว้ Private Aggregation เป็นหนึ่งในเกตที่มีให้ใช้งานสำหรับ Shared Storage API คุณจะอ่านค่าในพื้นที่เก็บข้อมูลที่แชร์ได้จากภายใน Worklet เท่านั้น และรายงานค่าเหล่านั้นได้โดยใช้การรวบรวมข้อมูลแบบส่วนตัวจาก Worklet

คุณยังเขียนไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจาก Worklet การเสนอราคา การให้คะแนน และการรายงานของ Protected Audience API ได้ด้วย ในภายหลัง คุณสามารถรายงานค่าเหล่านั้นในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันไปยังเซิร์ฟเวอร์ได้โดยใช้ Private Aggregation คุณยังใช้ค่าที่จัดเก็บไว้สําหรับการดําเนินการการเลือก URL ได้ด้วย

คุณเขียนคีย์และค่าใดก็ได้ลงในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้จาก Worklet ของ Protected Audience API

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

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

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

ดูข้อมูลเพิ่มเติมเกี่ยวกับพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้ในส่วนพื้นที่เก็บข้อมูลที่ใช้ร่วมกันของคู่มือนักพัฒนาซอฟต์แวร์การรายงาน Protected Audience API, คำอธิบาย, การสาธิตแบบเรียลไทม์ และโค้ดสาธิตใน GitHub

ขั้นตอนถัดไปคือ

เราต้องการพูดคุยกับคุณเพื่อให้แน่ใจว่าเราได้สร้าง API ที่เหมาะสำหรับทุกคน

พูดคุยเกี่ยวกับ API

API นี้จะได้รับการจัดทำเอกสารและอภิปรายต่อสาธารณะเช่นเดียวกับ Privacy Sandbox API อื่นๆ

ทดลองใช้ API

คุณจะทดสอบและเข้าร่วมในการพูดคุยเกี่ยวกับ Protected Audience API ได้