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

วัดข้อมูลและผลลัพธ์ของการประมูล Protected Audience API

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

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

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

หมายเหตุ: เราขอแนะนำให้คุณอ่านเอกสารเกี่ยวกับการรวมเนื้อหาแบบส่วนตัว, Fenced Frame, พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน และ Attribution Reporting ก่อนที่จะดำเนินการต่อ เนื่องจากมีการอธิบายแนวคิดหลักไว้ในเอกสารนี้

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

วันที่

เวิร์กโฟลว์โดยรวมของกลุ่มเป้าหมายที่มีการป้องกัน

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

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

ตำแหน่งการรายงาน

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

ระยะเวลา	ปลายทาง	ตำแหน่ง	มีข้อมูล	API การรายงานพร้อมใช้งาน
ประมูล	ผู้ซื้อ	generateBid()	สัญญาณ ผลการประมูล และประสิทธิภาพการประมูล	Private Aggregation API
		reportWin()		Private Aggregation API Ads Reporting API
	ผู้ขาย	scoreAd()		Private Aggregation API
		reportResult()		Private Aggregation API Ads Reporting API
แสดงผล	ผู้ซื้อ / ผู้ขาย	เฟรมบนเว็บไซต์ของผู้เผยแพร่โฆษณา	ข้อมูลระดับเหตุการณ์ภายในเฟรมโฆษณา	Private Aggregation API Ads Reporting API
Conversion	ผู้ซื้อ / ผู้ขาย	เว็บไซต์ Conversion	ข้อมูลระดับ Conversion และระดับเหตุการณ์จากเว็บไซต์ Conversion	Attribution Reporting API API การรวมข้อมูลส่วนตัว API การรายงานโฆษณา

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

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

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

สัญญาณ

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

สัญญาณ	คำอธิบาย	ตั้งค่าตำแหน่ง	ผู้ใช้	ความพร้อมใช้งาน
auctionSignals	ข้อมูลที่มีในบริบทของที่ที่มีการประมูล ข้อมูลนี้อาจรวมถึงข้อมูลเนื้อหาของหน้า ข้อมูลผู้ใช้จากบุคคลที่หนึ่ง และอื่นๆ	กำหนดโดยผู้ขายจากเว็บไซต์ของผู้เผยแพร่โฆษณาในการกำหนดค่าการประมูล	Buyer Seller	generateBid scoreAd report รายงานการชนะ
directFromSellerSignals	ข้อมูลเดียวกันสำหรับ auctionSignals, perBuyerSignals, sellerSignals แต่รับประกันว่าสัญญาณจะมาจากผู้ขายที่ระบุ	ตั้งค่าผ่านทางส่วนหัวการตอบกลับ HTTP จากผู้ขาย	Buyer Seller	generateBid scoreAd report รายงานการชนะ
browserSignals	ข้อมูลต่างๆ ที่เบราว์เซอร์ระบุ (topWindowHostname, interestGroupOwner, renderUrl, adComponents, biddingDurationMsec, IGJoinCount, IGRecency, modelingSignals)	ตั้งค่าโดยเบราว์เซอร์	Buyer Seller	generateBid scoreAd report รายงานการชนะ
sellerSignals	สัญญาณที่มอบให้ผู้ขายสำหรับการให้คะแนนโฆษณา	กำหนดโดยผู้ขายจากเว็บไซต์ของผู้เผยแพร่โฆษณาในการกำหนดค่าการประมูล	ผู้ขาย	scoreAd reportWin reportResult
trustedScoringSignals	สัญญาณแบบเรียลไทม์สำหรับการให้คะแนนโฆษณาให้แก่ผู้ขาย	URL ได้รับการตั้งค่าโดยผู้ขายจากเว็บไซต์ของผู้เผยแพร่โฆษณาในการกำหนดค่าการประมูล	ผู้ขาย	ผลลัพธ์รายงาน ScoreAd
perBuyerSignals	ข้อมูลบริบทการประมูลที่ให้กับผู้ซื้อที่เฉพาะเจาะจง ผู้ขายสามารถดึงมูลค่าสำหรับผู้ซื้อก่อนที่การประมูลจะเริ่มขึ้น นี่คือข้อมูลที่ผู้ซื้อทราบเกี่ยวกับโอกาสในการโฆษณา	กำหนดโดยผู้ขายจากเว็บไซต์ของผู้เผยแพร่โฆษณาในการกำหนดค่าการประมูล	ผู้ซื้อ	generateBid scoreAd report รายงานการชนะ
trustedBiddingSignals	สัญญาณแบบเรียลไทม์ที่มอบให้ผู้ซื้อสำหรับการเสนอราคาโฆษณา	URL จะถูกตั้งค่าโดยผู้ซื้อจากเว็บไซต์ของผู้ลงโฆษณาเมื่อตั้งค่ากลุ่มความสนใจ	ผู้ซื้อ	generateBid
userBiddingSignals	ข้อมูลผู้ใช้ที่ได้จากผู้ซื้อ	ตั้งค่าโดยผู้ซื้อจากเว็บไซต์ของผู้ลงโฆษณาเมื่อมีการตั้งค่ากลุ่มความสนใจ	ผู้ซื้อ	generateBid

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

ข้อมูลอื่นๆ ที่มี

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

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

นอกการประมูล Protected Audience API จะมีระยะเวลา 2 ช่วงที่สามารถรายงานข้อมูลได้

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

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

// 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 ที่แสดงโฆษณา เนื่องจากโฆษณาจะแสดงหลังจากที่การประมูลสรุปผลแล้ว สัญญาณการประมูลจึงไม่อยู่ภายในเฟรมที่แสดงโฆษณา ในการเชื่อมโยงข้อมูลเหล่านี้จากช่วงเวลาที่แตกต่างกัน เรามีกลไกการเปลี่ยนสองแบบให้คุณสร้างรายงานการมีส่วนร่วม

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

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

Ads Reporting API สำหรับเฟรมและ iframe ที่มีการปิดกั้น

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

ในเวิร์กเล็ตการรายงานของ 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']
});

นอกจากนี้ API การรายงานโฆษณา Fenced Frames จะยังใช้งานได้จนถึงปี 2026 เป็นอย่างน้อยด้วยเหตุผลเดียวกับการชนะการรายงาน

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

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

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

ระบบจะจำกัดสิทธิ์เข้าถึงเครือข่ายในอนาคต

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

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

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

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

โปรดดูข้อมูลเพิ่มเติมในส่วน Attribution Reporting ในตัวอธิบาย Ads Reporting API

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

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

ในเวิร์กโฟลว์นี้ ผู้ซื้อจะประสานงานกับผู้ขายเพื่อส่งรหัสที่ไม่ซ้ำกันเข้าร่วมการประมูล โดยในระหว่างการประมูล ผู้ซื้อจะส่งรหัสที่ไม่ซ้ำกันนี้พร้อมกับข้อมูลการประมูล ในระหว่างการแสดงผลและเวลา Conversion ระบบจะส่งข้อมูลจากเฟรมที่มีการปิดกั้นหรือ 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 โดยตอบกลับคำขอบีคอนด้วยส่วนหัว Attribution-Reporting-Register-Source
4. ในระหว่างเวลาที่เกิด Conversion คุณจะเรียกใช้แหล่งที่มาที่ลงทะเบียนไว้ในระหว่างเวลาการประมูลได้

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

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

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

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

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

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

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

คุณรวบรวมสัญญาณที่มีภายใน Worklet กับเซิร์ฟเวอร์ของคุณได้โดยใช้ Private Aggregation สำหรับการรวมสัญญาณ คุณสามารถใช้เมธอด privateAggregation.contributeToHistogram() ที่มีอยู่ในเวิร์กเล็ตการเสนอราคาของผู้ซื้อ, 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)

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

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

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

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