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

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

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

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

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

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

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

เวิร์กโฟลว์โดยรวมของ Protected Audience

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

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

การรายงานสถานที่

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

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

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

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

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

สัญญาณ

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

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

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

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

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

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

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

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

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

ในเวิร์กเล็ตการรายงานของ 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() ดังที่กล่าวถึงในส่วนกลไกการรายงานระดับเหตุการณ์การประมูลด้านบน

เราจะจํากัดการเข้าถึงเครือข่ายเป็นระยะเวลาหนึ่งหลังจากเลิกใช้งานคุกกี้ของบุคคลที่สาม

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

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

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

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

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

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

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

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

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 หากต้องการเรียนรู้เพิ่มเติม โปรดดูคำอธิบาย

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

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

ดูคำอธิบายเพื่อเรียนรู้เพิ่มเติม

การจัดเก็บสัญญาณการประมูลในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

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

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

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