วัดข้อมูลและผลลัพธ์ของการประมูล 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 กับสัญญาณการประมูลได้
- พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ซึ่งให้คุณเขียนสัญญาณการประมูลไปยังพื้นที่เก็บข้อมูลแบบข้ามต้นทาง แล้วให้คุณรายงานข้อมูลดังกล่าวในภายหลังได้โดยใช้การรวบรวมข้อมูลส่วนตัว
ภาพรวมการรายงานของ Protected Audience API
![เวิร์กโฟลว์โดยรวมของ Protected Audience](https://developers.google.cn/static/privacy-sandbox/assets/images/protected-audience-overal-cd55be71ecfa2.png?hl=th)
ระยะเวลาหลักที่รายงานข้อมูลขั้นตอนการประมูลของ 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 | ข้อมูลที่มีในบริบทของที่ที่มีการประมูล ข้อมูลนี้อาจรวมถึงข้อมูลเนื้อหาของหน้า ข้อมูลผู้ใช้จากบุคคลที่หนึ่ง และอื่นๆ | กำหนดโดยผู้ขายจากเว็บไซต์ของผู้เผยแพร่โฆษณาในการกำหนดค่าการประมูล | ผู้ซื้อ ผู้ขาย |
generateBid scoreAd report รายงานการชนะ |
directFromSellerSignals | ข้อมูลเดียวกันสำหรับ auctionSignals , perBuyerSignals , sellerSignals แต่รับประกันว่าสัญญาณจะมาจากผู้ขายที่ระบุ |
ตั้งค่าผ่านทางส่วนหัวการตอบกลับ HTTP จากผู้ขาย | ผู้ซื้อ ผู้ขาย |
generateBid scoreAd report รายงานการชนะ |
browserSignals | ข้อมูลต่างๆ ที่เบราว์เซอร์ระบุ (topWindowHostname , interestGroupOwner , renderUrl , adComponents , biddingDurationMsec , IGJoinCount , IGRecency , modelingSignals ) |
ตั้งค่าโดยเบราว์เซอร์ | ผู้ซื้อ ผู้ขาย |
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 สำหรับการเชื่อมโยงข้อมูลการประมูลกับข้อมูลระดับเหตุการณ์จากโฆษณาแบบเฟรมที่มีการปิดกั้น
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 ด้วยรหัสที่ไม่ซ้ำกันเดียวกัน จากนั้นจะใช้รหัสที่ไม่ซ้ำกันเพื่อเชื่อมโยงรายงานเหล่านี้เข้าด้วยกัน
ขั้นตอนการทำงาน:
- ก่อนที่การประมูลจะเริ่มขึ้น ผู้ซื้อจะส่งรหัสที่ไม่ซ้ำกันให้กับผู้ขาย ซึ่งเป็นส่วนหนึ่งของการเสนอราคาตอบด้วยการเสนอราคาแบบเรียลไทม์ ("RTB") แบบเป็นโปรแกรม คุณตั้งรหัสเป็นตัวแปรได้ เช่น
auctionId
มีการส่งรหัสเป็นperBuyerSignals
ในauctionConfig
และจะใช้ได้ในเวิร์กเล็ตของผู้ซื้อ - ในระหว่างเวลาประมูล ผู้ซื้อสามารถลงทะเบียนบีคอนโฆษณาเพื่อทริกเกอร์ในระหว่างเวลาในการแสดงโฆษณาและเวลาที่เกิด Conversion (
registerAdBeacon()
)- หากต้องการเชื่อมโยงสัญญาณการประมูลสำหรับเหตุการณ์เฟรมโฆษณา ให้ตั้งค่า
auctionId
เป็นพารามิเตอร์การค้นหาของ URL บีคอน - หากต้องการเชื่อมโยงสัญญาณการประมูลสำหรับเหตุการณ์ Conversion ให้ตั้งค่า
auctionId
ใน URL บีคอน
- หากต้องการเชื่อมโยงสัญญาณการประมูลสำหรับเหตุการณ์เฟรมโฆษณา ให้ตั้งค่า
- ในระหว่างที่มีการแสดงโฆษณา ระบบสามารถเรียกใช้หรือปรับปรุงบีคอนที่ลงทะเบียนไว้ในระหว่างเวลาการประมูลโดยใช้ข้อมูลระดับเหตุการณ์
- ทริกเกอร์เหตุการณ์เฟรมด้วย
reportEvent()
และส่งข้อมูลระดับเหตุการณ์ - เพิ่มเพย์โหลดระดับเหตุการณ์ลงในบีคอนการระบุแหล่งที่มาด้วย
setReportEventDataForAutomaticBeacons()
- ลงทะเบียนโฆษณากับ Attribution Reporting API โดยตอบกลับคำขอบีคอนด้วยส่วนหัว
Attribution-Reporting-Register-Source
- ทริกเกอร์เหตุการณ์เฟรมด้วย
- ในระหว่างเวลาที่เกิด 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 ได้