สร้างรายงานข้อมูลรวมโดยใช้ข้อมูลจาก Protected Audience และข้อมูลข้ามเว็บไซต์จากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
ในการมอบฟีเจอร์สำคัญๆ ที่เว็บต้องใช้ การรวบรวมข้อมูลแบบส่วนตัว API ได้สร้างขึ้นสำหรับการรวมและรายงานเกี่ยวกับข้อมูลแบบข้ามเว็บไซต์ใน วิธีการรักษาความเป็นส่วนตัว
สถานะการใช้งาน
ข้อเสนอ | สถานะ |
---|---|
ป้องกันรายงาน Private Aggregation API ที่ไม่ถูกต้องด้วยการยืนยันรายงานสำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คำอธิบาย |
พร้อมใช้งานใน Chrome |
ความพร้อมใช้งานของโหมดแก้ไขข้อบกพร่องการรวมข้อมูลส่วนตัวขึ้นอยู่กับการมีสิทธิ์ของบุคคลที่สาม ปัญหาเกี่ยวกับ GitHub |
พร้อมใช้งานใน Chrome M119 |
การลดความล่าช้าของรายงาน คำอธิบาย |
พร้อมใช้งานใน Chrome M119 |
การสนับสนุนสำหรับ Private Aggregation API และบริการรวมข้อมูลสำหรับ Google Cloud คำอธิบาย |
พร้อมใช้งานใน Chrome M121 |
การเพิ่มระยะห่างจากขอบสำหรับเพย์โหลดรายงานที่รวบรวมได้ คำอธิบาย |
พร้อมใช้งานใน Chrome M119 |
โหมดแก้ไขข้อบกพร่องของการรวมข้อมูลส่วนตัวพร้อมใช้งานสำหรับการรายงานionReportBuyers คำอธิบาย |
คาดหวังใน Chrome M123 |
การรองรับรหัสการกรอง คำอธิบาย |
คาดหวังใน Chrome M128 |
Private Aggregation API คืออะไร
Private Aggregation API ช่วยให้นักพัฒนาแอปสร้างรายงานข้อมูลรวมได้ โดยใช้ข้อมูลจาก Protected Audience API และ ข้อมูลข้ามเว็บไซต์จากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
ฟังก์ชันหลักของ API นี้เรียกว่า contributeToHistogram()
การดำเนินการฮิสโตแกรมช่วยให้คุณรวบรวมข้อมูล
จากผู้ใช้ในแต่ละที่เก็บข้อมูล (รู้จักกันใน API ว่าเป็นคีย์การสรุปรวม) ที่คุณกำหนด
การเรียกฮิสโตแกรมจะรวบรวมค่าและแสดงผลลัพธ์แบบรวมที่มีเสียงรบกวนใน
รูปแบบของรายงานสรุป ตัวอย่างเช่น รายงานอาจแสดงจำนวน
เว็บไซต์ที่ผู้ใช้แต่ละรายเห็นเนื้อหาของคุณ หรือพบข้อบกพร่องในสคริปต์ของบุคคลที่สาม การดำเนินการนี้ดำเนินการภายในเวิร์กเล็ตของ API อื่น
ตัวอย่างเช่น หากก่อนหน้านี้คุณได้บันทึกข้อมูลประชากรและข้อมูลทางภูมิศาสตร์ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถใช้ Private Aggregation API เพื่อสร้างฮิสโตแกรมที่บอกให้คุณทราบถึงจำนวนผู้ใช้ในนิวยอร์กซิตี้ที่ดูเนื้อหาข้ามเว็บไซต์โดยประมาณ ในการรวมสำหรับการวัดนี้ คุณสามารถเข้ารหัสมิติข้อมูลภูมิศาสตร์ลงในคีย์การสรุปรวมและนับจำนวนผู้ใช้ในค่าที่รวบรวมได้
หัวข้อสำคัญ
เมื่อคุณเรียกใช้ Private Aggregation API ด้วยคีย์การรวมและค่าที่รวบรวมได้ เบราว์เซอร์จะสร้างรายงานที่รวบรวมได้
ระบบจะส่งรายงานที่รวบรวมได้ไปยังเซิร์ฟเวอร์ของคุณเพื่อรวบรวมและจัดกลุ่ม รายงานแบบกลุ่มจะได้รับการประมวลผลในภายหลังโดยบริการรวบรวมข้อมูล และจะสร้างรายงานสรุป
โปรดดูเอกสารข้อมูลพื้นฐานเกี่ยวกับ Private Aggregation API เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับแนวคิดหลักที่เกี่ยวข้องกับ Private Aggregation API
ความแตกต่างจากการรายงานการระบุแหล่งที่มา
Private Aggregation API มีความคล้ายคลึงกันหลายอย่างกับ Attribution Reporting API Attribution Reporting เป็น API แบบสแตนด์อโลนที่ออกแบบมาเพื่อวัด Conversion ขณะที่ Private Aggregation สร้างขึ้นเพื่อการวัดผลข้ามเว็บไซต์ร่วมกับ API เช่น Protected Audience API และพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน API ทั้ง 2 นี้จะสร้างรายงานที่รวบรวมได้ซึ่งแบ็กเอนด์ของบริการรวบรวมข้อมูลใช้เพื่อสร้างรายงานสรุป
การรายงานการระบุแหล่งที่มาจะเชื่อมโยงข้อมูลที่รวบรวมจากเหตุการณ์การแสดงผลและเหตุการณ์ Conversion ซึ่งเกิดขึ้นในเวลาที่ต่างกัน การรวมข้อมูลส่วนตัวจะวัดเหตุการณ์เดียวแบบข้ามเว็บไซต์
ทดสอบ API นี้
หากต้องการทดสอบ Private Aggregation API ในเครื่อง ให้เปิดใช้ API ความเป็นส่วนตัวเกี่ยวกับโฆษณาทั้งหมดภายใต้ chrome://settings/adPrivacy
อ่านเพิ่มเติมเกี่ยวกับการทดสอบในการทดสอบและเข้าร่วม
ใช้การสาธิต
โดยคุณจะเข้าถึงการสาธิต Private Aggregation API สำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้ที่ goo.gle/shared-storage-demo ส่วนโค้ดจะอยู่ใน GitHub การสาธิตจะใช้การดำเนินการฝั่งไคลเอ็นต์และสร้างรายงานที่รวบรวมได้ซึ่งส่งไปยังเซิร์ฟเวอร์ของคุณ
จะมีการเผยแพร่การสาธิต Private Aggregation API สำหรับ Protected Audience API ในอนาคต
กรณีการใช้งาน
การรวมข้อมูลส่วนตัวเป็น API วัตถุประสงค์ทั่วไปสําหรับการวัดผลข้ามเว็บไซต์ และพร้อมให้ใช้งานในเวิร์กเล็ตพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและ Protected Audience API ขั้นตอนแรกคือการตัดสินใจอย่างเฉพาะเจาะจงว่าคุณต้องการรวบรวมข้อมูลใด จุดข้อมูลเหล่านั้นเป็นพื้นฐานของคีย์การรวม
พร้อมพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
พื้นที่เก็บข้อมูลที่ใช้ร่วมกันช่วยให้คุณอ่านและเขียนข้อมูลข้ามเว็บไซต์ในสภาพแวดล้อมที่ปลอดภัยเพื่อป้องกันการรั่วไหล และ Private Aggregation API จะช่วยให้คุณวัดข้อมูลข้ามเว็บไซต์ที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้
การวัด Unique Reach
คุณอาจต้องวัดจำนวนผู้ใช้ที่ไม่ซ้ำที่ดูเนื้อหาของตน API การรวมข้อมูลส่วนตัวจะให้คำตอบเช่น "ผู้ใช้ที่ไม่ซ้ำประมาณ 317 คนเคยเห็น Content ID 861"
คุณสามารถตั้งค่าสถานะในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่อแสดงว่าผู้ใช้ได้เห็นเนื้อหาแล้วหรือยัง ในการเข้าชมครั้งแรกที่ไม่มี Flag ใดๆ จะมีการเรียกใช้ Private Aggregation แล้วมีการตั้งค่าแฟล็ก สำหรับการเข้าชมครั้งต่อๆ ไปของผู้ใช้ ซึ่งรวมถึงการเข้าชมข้ามเว็บไซต์ คุณสามารถตรวจสอบพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน และข้ามการส่งรายงานไปยังการรวมข้อมูลแบบส่วนตัวได้หากมีการตั้งธงไว้ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการตามการวัดผลได้จากสมุดปกขาวเพื่อการเข้าถึง
การวัดข้อมูลประชากร
คุณอาจต้องการวัดข้อมูลประชากรของผู้ใช้ที่ได้ดูเนื้อหาของคุณในเว็บไซต์ต่างๆ
การรวบรวมข้อมูลแบบส่วนตัวจะให้คำตอบ เช่น "ผู้ใช้ที่ไม่ซ้ำประมาณ 317 คนมาจากอายุ 18-45 ปีและมาจากประเทศเยอรมนี" ใช้พื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่อเข้าถึงข้อมูลประชากรจากบริบทของบุคคลที่สาม หลังจากนั้น คุณสามารถสร้างรายงานที่มีการรวมข้อมูลแบบส่วนตัวได้โดยการเข้ารหัสมิติข้อมูลกลุ่มอายุและประเทศในคีย์การรวม
การวัดความถี่ K+
คุณอาจต้องวัดจำนวนผู้ใช้ที่เห็นเนื้อหาหรือโฆษณาหนึ่งๆ อย่างน้อย K ครั้งในเบราว์เซอร์หนึ่งๆ สำหรับค่าที่เลือกไว้ล่วงหน้าเป็น K
การรวบรวมข้อมูลแบบส่วนตัวจะให้คำตอบเช่น "ผู้ใช้ประมาณ 89 คนเห็น Content ID 581 อย่างน้อย 3 ครั้ง" คุณจะเพิ่มพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจากเว็บไซต์ต่างๆ ได้ ซึ่งจะอ่านใน Worklet ได้ เมื่อนับรวมถึง K แล้ว คุณจะส่งรายงานผ่านการรวมข้อมูลแบบส่วนตัวได้
ใช้ Protected Audience API
โดย Protected Audience API จะเปิดใช้การกำหนดเป้าหมายใหม่และ Use Case ของกลุ่มเป้าหมายที่กำหนดเอง ขณะที่การรวบรวมข้อมูลส่วนตัวช่วยให้คุณรายงานเหตุการณ์จากเวิร์กเล็ตผู้ซื้อและผู้ขายได้ API นี้ใช้สำหรับงานต่างๆ เช่น การวัดการกระจายตัวของราคาเสนอในการประมูล
คุณสามารถรวบรวมข้อมูลจาก Protected Audience API ได้โดยตรงโดยใช้ contributeToHistogram()
และรายงานข้อมูลตามทริกเกอร์โดยใช้ contributeToHistogramOnEvent()
ซึ่งเป็นส่วนขยายพิเศษสำหรับ Protected Audience API
ฟังก์ชันที่พร้อมใช้งาน
ฟังก์ชันต่อไปนี้มีอยู่ในออบเจ็กต์ privateAggregation
ที่ใช้ได้ในเวิร์กเล็ตพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและ Protected Audience API
contributeToHistogram()
คุณสามารถเรียกใช้ privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
โดยที่คีย์การรวมคือ bucket
และค่าที่รวมได้เป็น value
ต้องระบุ BigInt
สำหรับพารามิเตอร์ bucket
สำหรับพารามิเตอร์ value
คุณต้องระบุตัวเลขจำนวนเต็ม
ตัวอย่างการใช้ชื่อในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่อการวัดการเข้าถึงมีดังนี้
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
ตัวอย่างโค้ดด้านบนจะเรียกใช้ Private Aggregation เมื่อใดก็ตามที่มีการโหลดเนื้อหา iframe แบบข้ามเว็บไซต์ โค้ด iframe จะโหลด Worklet และ Worklet จะเรียก API การรวมข้อมูลส่วนตัวด้วย Content ID ที่แปลงเป็นคีย์การรวม (ที่เก็บข้อมูล)
contributeToHistogramOnEvent()
ภายในเวิร์กโฟลว์ Protected Audience API เท่านั้น เรามีกลไกตามทริกเกอร์สําหรับส่งรายงานเฉพาะเมื่อเกิดเหตุการณ์บางอย่างขึ้น ฟังก์ชันนี้ช่วยให้ที่เก็บข้อมูลและค่าขึ้นอยู่กับสัญญาณที่ยังไม่มีให้ใช้ ณ ขณะนั้นในการประมูล
เมธอด privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
จะใช้ eventType
ที่ระบุเหตุการณ์การทริกเกอร์ และ contribution
ที่จะส่งเมื่อมีการทริกเกอร์เหตุการณ์ เหตุการณ์ทริกเกอร์อาจมาจากการประมูลเองหลังจากที่การประมูลสิ้นสุดลง เช่น เหตุการณ์การชนะหรือแพ้การประมูล หรืออาจมาจากเฟรมที่มีการปิดกั้นซึ่งแสดงโฆษณา
หากต้องการส่งรายงานสำหรับเหตุการณ์การประมูล ให้ใช้คีย์เวิร์ดที่จองไว้ 2 รายการ ได้แก่ reserved.win
, reserved.loss
และ reserved.always
หากต้องการส่งรายงานที่ทริกเกอร์โดยเหตุการณ์จากเฟรมที่มีการปิดกั้น ให้กําหนดประเภทเหตุการณ์ที่กําหนดเอง หากต้องการทริกเกอร์เหตุการณ์จากเฟรมที่มีการปิดกั้น ให้ใช้เมธอด fence.reportEvent()
ที่มีอยู่จาก Fenced Frames Ads Reporting API
ตัวอย่างต่อไปนี้จะส่งรายงานการแสดงผลเมื่อมีการเรียกเหตุการณ์การชนะการประมูล และส่งรายงานการคลิกหากมีการทริกเกอร์เหตุการณ์ click
จากเฟรมที่มีการปิดกั้นซึ่งแสดงโฆษณา ค่าทั้งสองนี้สามารถใช้ในการคำนวณอัตราการคลิกผ่าน
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
โปรดดูข้อมูลเพิ่มเติมที่คำอธิบายการรายงานการรวมข้อมูลแบบส่วนตัวเพิ่มเติม
enableDebugMode()
แม้ว่าคุกกี้ของบุคคลที่สามจะยังคงใช้ได้ แต่เราจะมีกลไกชั่วคราวที่ช่วยให้แก้ไขข้อบกพร่องและทดสอบได้ง่ายขึ้นโดยการเปิดใช้โหมดแก้ไขข้อบกพร่อง รายงานแก้ไขข้อบกพร่องมีประโยชน์ในการเปรียบเทียบการวัดที่อิงตามคุกกี้กับการวัดแบบรวมแบบส่วนตัว และช่วยให้คุณตรวจสอบการผสานรวม API ได้อย่างรวดเร็วด้วย
การเรียกใช้ privateAggregation.enableDebugMode()
ใน Worklet จะเปิดใช้โหมดแก้ไขข้อบกพร่องซึ่งจะทำให้รายงานที่รวบรวมได้รวมเพย์โหลดที่ไม่เข้ารหัส (Cleartext) จากนั้นคุณอาจประมวลผลเพย์โหลดเหล่านี้ด้วยเครื่องมือทดสอบในเครื่องของบริการรวมข้อมูล
โหมดแก้ไขข้อบกพร่องจะใช้ได้เฉพาะกับผู้โทรที่ได้รับอนุญาตให้เข้าถึงเท่านั้น
คุกกี้ของบุคคลที่สาม หากผู้โทรไม่มีสิทธิ์เข้าถึงคุกกี้ของบุคคลที่สาม
enableDebugMode()
จะล้มเหลวโดยไม่มีการแจ้งเตือน ซึ่งหมายความว่าเมื่อบุคคลที่สาม
เลิกใช้งานคุกกี้แล้ว โหมดแก้ไขข้อบกพร่องจะใช้งานไม่ได้อีกต่อไป
คุณยังตั้งค่าคีย์การแก้ไขข้อบกพร่องได้โดยเรียกใช้ privateAggregation.enableDebugMode({ <debugKey: debugKey> })
ซึ่งสามารถใช้ BigInt
เป็นคีย์การแก้ไขข้อบกพร่องได้ คีย์การแก้ไขข้อบกพร่องใช้เพื่อเชื่อมโยงข้อมูลจากการวัดผลที่อิงตามคุกกี้และข้อมูลจากการวัดแบบรวมแบบส่วนตัวได้
เรียกได้ 1 ครั้งต่อบริบทเท่านั้น การโทรครั้งต่อๆ ไปจะมีข้อยกเว้น
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
รายงานการยืนยัน
สำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถยืนยันว่ารายงานที่รวบรวมได้ที่คุณได้รับนั้นถูกต้องโดยการเพิ่มรหัสบริบทในการเรียกใช้การดำเนินการพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ระบบจะแนบรหัสดังกล่าวไว้กับรายงานที่ส่ง โดยหลังจากนั้นคุณจะใช้รหัสดังกล่าวเพื่อยืนยันว่ามีการส่งรายงานมาจากการดำเนินการพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้
ดูข้อมูลเพิ่มเติมได้ที่คำอธิบายการยืนยันรายงาน
มีส่วนร่วมและแชร์ความคิดเห็น
Private Aggregation API อยู่ระหว่างการหารือและอาจมีการเปลี่ยนแปลงในอนาคต หากคุณลองใช้ API นี้และมีความคิดเห็น เรายินดีรับฟัง
- GitHub: อ่านวิดีโออธิบาย ตั้งคำถามและเข้าร่วมการสนทนา
- การสนับสนุนนักพัฒนาแอป: ถามคำถามและเข้าร่วมการสนทนาในที่เก็บการสนับสนุนนักพัฒนาซอฟต์แวร์ของ Privacy Sandbox
- เข้าร่วมกลุ่ม Shared Storage API และกลุ่ม Protected Audience API เพื่อดูประกาศล่าสุดที่เกี่ยวข้องกับการรวบรวมข้อมูลส่วนตัว