ดูวิธีการทำงานของรหัสการรายงานในการประมูลที่ใช้ Protected Audience
ภาพรวม
รหัสการรายงานคือตัวระบุที่เชื่อมโยงกับโฆษณาซึ่งพร้อมใช้งานในการสร้างราคาเสนอ การให้คะแนนราคาเสนอ และการรายงาน ผู้ซื้อจะระบุรหัสการรายงานในการกำหนดค่ากลุ่มความสนใจ และรหัสดังกล่าวจะพร้อมใช้งานใน generateBid(), scoreAd(), reportResult() และ reportWin() ภายใต้เงื่อนไขต่างๆ ที่กล่าวถึงในคู่มือนี้
รหัสการรายงานช่วยให้คุณรายงานตัวระบุสําหรับโฆษณา และยังเปิดใช้กรณีการใช้งานต่างๆ เช่น ดีล ได้อีกด้วย
รหัสการรายงานมี 3 ประเภท 2 ชนิด ดังนี้
- รหัสการรายงานที่เลือกไม่ได้
buyerReportingId(สตริง)buyerAndSellerReportingId(สตริง)
- รหัสการรายงานที่เลือกได้
selectableBuyerAndSellerReportingIds(อาร์เรย์ของสตริง)
รหัสการรายงานจะทํางานแตกต่างกันไป ขึ้นอยู่กับว่ามีการใช้รหัสการรายงานที่เลือกได้หรือไม่ เมื่อใช้เฉพาะรหัสการรายงานที่เลือกไม่ได้ รหัสเหล่านั้นจะพร้อมใช้งานภายในฟังก์ชันการรายงานเท่านั้น เมื่อใช้รหัสการรายงานที่เลือกได้พร้อมกับรหัสการรายงานที่เลือกไม่ได้ (หากจำเป็น) รหัสทั้งหมดที่กำหนดไว้จะพร้อมใช้งานใน generateBid() และ scoreAd() ด้วย
รหัสการรายงานที่เลือกไม่ได้
buyerReportingId และ buyerAndSellerReportingId คือรหัสการรายงานที่เลือกไม่ได้ซึ่งกำหนดไว้ในการกำหนดค่ากลุ่มความสนใจซึ่งจะพร้อมใช้งานในฟังก์ชันการรายงานของผู้ซื้อและผู้ขาย ฟังก์ชันการรายงานของผู้ซื้อและผู้ขายจะทํางานสําหรับโฆษณาที่ชนะเท่านั้น และฟังก์ชันจะได้รับรหัสการรายงานที่กําหนดไว้สําหรับโฆษณาที่ชนะนั้น
เมื่อใช้โดยไม่มีรหัสการรายงานที่เลือกได้ ฟังก์ชันการรายงานของผู้ซื้อจะได้รับ buyerReportingId หรือ buyerAndSellerReportingId ขึ้นอยู่กับลักษณะการทำงานของการเขียนทับ และฟังก์ชันการรายงานของผู้ขายจะได้รับ buyerAndSellerReportingId หากไม่ได้กำหนดทั้ง buyerReportingId และ buyerAndSellerReportingId ในการกำหนดค่ากลุ่มความสนใจ ฟังก์ชัน reportWin() จะได้รับชื่อกลุ่มความสนใจ (interestGroupName) ของราคาเสนอที่ชนะ
รหัสที่เลือกไม่ได้จะใช้ไม่ได้ภายใน generateBid() และ scoreAd() หากไม่ได้ใช้ร่วมกับรหัสการรายงานที่เลือกได้
การรายงานรหัสในกลุ่มความสนใจ
ผู้ซื้อจะเป็นผู้กำหนดรหัสการรายงานสำหรับโฆษณาแต่ละรายการในกลุ่มความสนใจ
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
// buyerAndSellerReportingId goes to the buyer and seller reporting functions
buyerAndSellerReportingId: 'bsrid123',
// buyerReportingId is defined here as an example, but
// is not used due to the overwrite rules described later
buyerReportingId: 'brid123',
}]
});
การรายงานของผู้ขาย
ในระหว่างระยะการรายงานของผู้ขาย ค่า buyerAndSellerReportingId จะพร้อมใช้งานสำหรับ reportResult() ดังนี้
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId // 'bsrid123'
} = browserSignals;
sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}
ก่อนที่รหัสจะพร้อมใช้งานภายใน reportResult() ระบบจะตรวจสอบ k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) หากไม่ใช่ k-anonymous reportResult() ฟังก์ชันจะยังคงทํางาน แต่ค่ารหัสการรายงานจะไม่พร้อมใช้งานภายในฟังก์ชัน
การรายงานของผู้ซื้อ
ในระหว่างระยะการรายงานของผู้ซื้อของการประมูล reportWin() จะได้รับรหัสการรายงาน 1 รายการ หากมีการกําหนดรหัสการรายงานมากกว่า 1 รายการในกลุ่มความสนใจ ระบบจะใช้กฎการเขียนทับที่ buyerAndSellerReportingId เขียนทับ buyerReportingId ดังนี้
- หากกำหนดทั้ง
buyerAndSellerReportingIdและbuyerReportingIdbuyerAndSellerReportingIdจะเขียนทับbuyerReportingIdและbuyerAndSellerReportingIdจะพร้อมใช้งานภายในreportWin() - หากกำหนดเฉพาะ
buyerReportingIdไว้buyerReportingIdจะพร้อมใช้งาน - หากไม่ได้กำหนดทั้ง
buyerAndSellerReportingIdและbuyerReportingIdinterestGroupNameจะพร้อมใช้งาน
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId // 'bsrid123'
} = browserSignals;
sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}
ระบบจะตรวจสอบรหัสการรายงานที่พร้อมใช้งานภายใน reportWin() เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนกว่าจะถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) หากไม่ผ่านการตรวจสอบ k-anonymity reportWin() จะยังคงทํางานต่อไป แต่ค่ารหัสการรายงานจะใช้ไม่ได้ภายในฟังก์ชัน
กำหนด buyerReportingId เท่านั้น
หากกำหนดเฉพาะ buyerReportingId ในการกำหนดค่ากลุ่มตามความสนใจ
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
}]
});
จากนั้น buyerReportingId จะพร้อมใช้งานภายใน reportWin()
function reportWin(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
} = browserSignals;
}
ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)
กำหนดเฉพาะ buyerAndSellerReportingId
หากกำหนดเฉพาะ buyerAndSellerReportingId ในการกำหนดค่ากลุ่มตามความสนใจ
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerAndSellerReportingId: 'bsrid123',
}]
});
จากนั้น buyerAndSellerReportingId จะพร้อมใช้งานภายใน reportWin()
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
} = browserSignals;
}
ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerAndSellerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)
กำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId
หากกำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId ในการกำหนดค่ากลุ่มความสนใจ
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
buyerAndSellerReportingId: 'bsrid123',
}]
});
จากนั้นจะมีเพียง buyerAndSellerReportingId ใน reportWin() เนื่องจากลักษณะการทำงานของการเขียนทับ
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
} = browserSignals;
}
ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerAndSellerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)
ไม่ได้กำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId
หากไม่ได้กำหนดรหัสการรายงานทั้ง 2 รายการในการกำหนดค่ากลุ่มความสนใจ ให้ทำดังนี้
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
}]
});
จากนั้นกลุ่มความสนใจ name จะพร้อมใช้งานภายใน reportWin()
function reportWin(..., browserSignals, ...) {
const {
interestGroupName, // 'example-interest-group'
} = browserSignals;
}
ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบชื่อกลุ่มความสนใจ (interestGroupName) เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนกว่าจะถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)
รหัสการรายงานที่เลือกได้
รหัสการรายงานที่เลือกได้ช่วยให้ผู้ซื้อเลือกรหัสได้ในระหว่างการสร้างราคาเสนอ และเบราว์เซอร์จะทำให้ค่าที่เลือกพร้อมใช้งานสำหรับ scoreAd() และฟังก์ชันการรายงาน selectableBuyerAndSellerReportingIds ซึ่งเป็นอาร์เรย์ของสตริงจะระบุไว้ใน generateBid() และผู้ซื้อจะส่งคืนรหัสที่เลือก 1 รายการเป็น selectedBuyerAndSellerReportingId ได้
ฟังก์ชัน generateBid() และ scoreAd() จะทํางานสําหรับโฆษณาแต่ละรายการที่กําหนดไว้ในการกําหนดค่ากลุ่มความสนใจ และรับรหัสการรายงานสําหรับโฆษณาแต่ละรายการ ฟังก์ชันการรายงานของผู้ซื้อและผู้ขายจะทํางานสําหรับโฆษณาที่ชนะเท่านั้น และฟังก์ชันจะได้รับรหัสการรายงานที่กําหนดไว้สําหรับโฆษณาที่ชนะนั้น
เมื่อใช้รหัสการรายงานที่เลือกไม่ได้ร่วมกับรหัสการรายงานที่เลือกได้ ลักษณะการทำงานของรหัสการรายงานที่เลือกไม่ได้จะเปลี่ยนไปจากเวิร์กโฟลว์ที่อธิบายไว้ในส่วนก่อนหน้า ซึ่งแตกต่างจากลักษณะการทำงานเริ่มต้นของรหัสการรายงานที่เลือกไม่ได้ซึ่งใช้ได้เฉพาะภายในฟังก์ชันการรายงาน รหัสการรายงานที่เลือกได้จะช่วยให้รหัสการรายงานที่เลือกไม่ได้พร้อมใช้งานภายใน generateBid() และ scoreAd() ด้วย
กลุ่มความสนใจ
ฟิลด์รหัสการรายงานที่เลือกได้ - selectableBuyerAndSellerReportingIds - คืออาร์เรย์ของสตริงที่ผู้ซื้อกำหนดในกลุ่มความสนใจสำหรับโฆษณา คุณยังกําหนดรหัสการรายงานที่เลือกไม่ได้ควบคู่ไปกับรหัสการรายงานที่เลือกได้ด้วย
navigator.joinAdInterestGroup({
owner: 'https://buyer.example',
name: 'example-interest-group',
ads: [{
renderUrl: `https://buyer.example/ad.html`,
buyerReportingId: 'brid123',
buyerAndSellerReportingId: 'bsrid123',
selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
}]
});
การสร้างราคาเสนอของผู้ซื้อ
หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ ก็จะใช้ได้ภายใน generateBid() พร้อมกับรหัสการรายงานอื่นๆ ที่กำหนดไว้
function generateBid(interestGroup, ...) {
const [{
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
}] = interestGroup.ads;
return {
bid: 1,
render: 'https://buyer.example/ad.html',
selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
};
}
ผู้ซื้อสามารถเลือก 1 ในรหัสจากอาร์เรย์ selectableBuyerAndSellerReportingIds ใน generateBid() และส่งคืนรหัสที่เลือกเป็น selectedBuyerAndSellerReportingId ระบบจะปฏิเสธราคาเสนอหากค่าที่เลือกไม่อยู่ในอาร์เรย์ selectableBuyerAndSellerReportingIds หากกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และผู้ซื้อไม่แสดง selectedBuyerAndSellerReportingId จาก generateBid() รหัสการรายงานจะเปลี่ยนกลับเป็นลักษณะการทำงานที่อธิบายไว้สำหรับรหัสการรายงานที่เลือกไม่ได้
ราคาเสนอที่มีค่าที่ส่งคืนสำหรับ selectedbuyerAndSellerReportingId อาจชนะการประมูลได้ก็ต่อเมื่อค่าของ selectedbuyerAndSellerReportingId เป็นแบบ k-anonymous ร่วมกับ buyerAndSellerReportingId (หากมี), buyerReportingId (หากมี), เจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)
การให้คะแนนโฆษณาของผู้ขาย
สำหรับผู้ขาย selectedBuyerAndSellerReportingId ที่ผู้ซื้อส่งคืนจาก generateBid() จะพร้อมใช้งานใน scoreAd() พร้อมกับ buyerAndSellerReportingId หากมีการกำหนดไว้ในการกำหนดค่ากลุ่มความสนใจ
function scoreAd(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId, // 'sbsrid2'
} = browserSignals;
// ...
}
การรายงานของผู้ขาย
สำหรับการรายงานของผู้ขาย selectedBuyerAndSellerReportingId ที่ผู้ซื้อส่งคืนจาก generateBid() จะพร้อมใช้งานใน reportResult() พร้อมกับ buyerAndSellerReportingId หากมีการกำหนดไว้ในกลุ่มความสนใจ
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และ selectedBuyerAndSellerReportingId แสดงผลจาก generateBid() ก็จะชนะการประมูลไม่ได้ เว้นแต่ selectedBuyerAndSellerReportingId และ buyerAndSellerReportingId (หากมี) จะเป็นแบบ k-anonymous กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) และจะไม่ดำเนินการ reportResult() สำหรับราคาเสนอนั้น ดังนั้น หากมีการเรียกใช้ reportResult() โดยมีค่าสำหรับ selectedBuyerAndSellerReportingId แสดงว่ารหัสการรายงานผ่านการตรวจสอบ k-anonymity และรหัสการรายงานทั้งหมดที่กำหนดจะพร้อมใช้งานภายใน reportResult()
การรายงานของผู้ซื้อ
หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และ selectedBuyerAndSellerReportingId ได้รับจาก generateBid() รหัสการรายงานทั้งหมดที่กำหนดในการกำหนดค่ากลุ่มความสนใจจะพร้อมใช้งาน โปรดทราบว่าเช่นเดียวกับการรายงานของผู้ขาย หากรหัสการรายงานไม่เป็นแบบ k-anonymous รหัสเหล่านั้นจะไม่ชนะการประมูลและreportWin()จะไม่ทํางานสําหรับราคาเสนอนั้น
function reportWin(..., browserSignals, ...) {
const {
buyerReportingId, // 'brid123'
buyerAndSellerReportingId, // 'bsrid123'
selectedBuyerAndSellerReportingId // 'sbsrid2'
} = browserSignals;
// ...
}
กฎการเขียนทับ
เราจะสรุปกฎการลบล้างสำหรับทั้งรหัสการรายงานที่เลือกไม่ได้และรหัสการรายงานที่เลือกได้ เบราว์เซอร์จะเป็นตัวกำหนดว่า selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId และชื่อกลุ่มความสนใจใดจะส่งไปยัง reportWin() โดยใช้ตรรกะต่อไปนี้
- หากระบบแสดงผล
selectedBuyerAndSellerReportingIdจากราคาเสนอselectedBuyerAndSellerReportingId,buyerAndSellerReportingId(หากกำหนดไว้ในกลุ่มความสนใจ) และbuyerReportingId(หากกำหนดไว้ในกลุ่มความสนใจ) จะพร้อมใช้งานสำหรับการรายงาน - มิฉะนั้น หากมีการกำหนด
buyerAndSellerReportingIdในกลุ่มความสนใจ ก็จะมีเฉพาะbuyerAndSellerReportingIdเท่านั้นที่ใช้ได้สำหรับการรายงาน - มิฉะนั้น หากมีการกำหนด
buyerReportingIdในกลุ่มความสนใจ ก็จะมีเฉพาะbuyerReportingIdเท่านั้นที่ใช้ได้สำหรับการรายงาน - มิฉะนั้น จะมีเพียงกลุ่มความสนใจ
nameเท่านั้นที่พร้อมสำหรับการรายงาน
ตารางต่อไปนี้อธิบายลักษณะการทำงานของการเขียนทับ
| มีการกำหนดรหัสการรายงานในการกำหนดค่ากลุ่มความสนใจหรือไม่ | รหัสการรายงานที่ใช้ได้ | |||
selectableBuyerAnd
|
buyerAndSeller
|
buyerReportingId
|
reportWin()
|
reportResult()
|
| ใช่ และเลือก ใน generateBid()
|
ไม่บังคับ | ไม่บังคับ |
1) selectedBuyerAnd2) buyerAndSeller (หากกำหนดไว้)3) buyerReportingId (หากกำหนดไว้)
|
1) selectedBuyerAnd2) buyerAndSeller (หากกำหนด) |
| ไม่ได้เลือก ใน generateBid() |
มี | ละเว้นแล้ว | buyerAndSeller |
buyerAndSeller |
| ไม่ได้เลือก ใน generateBid() |
ไม่ | มี | buyerReportingId |
ไม่มี |
| ไม่ได้เลือก ใน generateBid() |
ไม่ | ไม่ | interestGroupName |
ไม่มี |
มีส่วนร่วมและแชร์ความคิดเห็น
- ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสการรายงานได้ที่ส่วนรหัสการรายงานของคำอธิบาย Protected Audience
- GitHub: ตั้งคำถามและติดตามการสนทนาในปัญหาในที่เก็บ API
- W3C: พูดคุยเกี่ยวกับกรณีการใช้งานในอุตสาหกรรมในการประชุม WICG
- ประกาศ: เข้าร่วมหรือดูรายชื่ออีเมล
- การสนับสนุนนักพัฒนาแอปของ Privacy Sandbox: ถามคำถามและเข้าร่วมการสนทนาในที่เก็บการสนับสนุนนักพัฒนาแอปของ Privacy Sandbox
- Chromium: รายงานข้อบกพร่องของ Chromium เพื่อถามคำถามเกี่ยวกับการติดตั้งใช้งานที่พร้อมให้ทดสอบใน Chrome