สร้างรายงานข้อมูลรวมโดยใช้ข้อมูลจาก Protected Audience และข้อมูลข้ามเว็บไซต์จากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
Private Aggregation API จึงสร้างขึ้นเพื่อการรวบรวมและการรายงานข้อมูลข้ามเว็บไซต์ในลักษณะที่รักษาความเป็นส่วนตัว เพื่อให้บริการฟีเจอร์สำคัญๆ ที่เว็บต้องใช้
สถานะการใช้งาน
ข้อเสนอ | สถานะ |
---|---|
ป้องกันรายงาน Private Aggregation API ที่ไม่ถูกต้องด้วยการยืนยันรายงานสำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คำอธิบาย |
พร้อมใช้งานใน Chrome |
ความพร้อมใช้งานของโหมดแก้ไขข้อบกพร่องของการรวมส่วนตัวขึ้นอยู่กับการมีสิทธิ์ของ 3PC ปัญหาเกี่ยวกับ GitHub |
พร้อมใช้งานใน Chrome M119 |
การลดความล่าช้าของรายงาน คำอธิบาย |
พร้อมใช้งานใน Chrome M119 |
การรองรับ Private Aggregation API และบริการรวบรวมสำหรับ Google Cloud Explain |
พร้อมใช้งานใน Chrome M121 |
ระยะห่างจากขอบสำหรับเพย์โหลดของรายงานที่รวบรวมได้ คำอธิบาย |
พร้อมใช้งานใน Chrome M119 |
โหมดแก้ไขข้อบกพร่องของการรวมส่วนตัวที่พร้อมใช้งานสําหรับการรายงาน KubernetesReportBuyers คําอธิบาย |
คาดว่าใน Chrome M123 |
การรองรับการกรองรหัส คำอธิบาย |
คาดว่าจะเปิดตัวครั้งแรกใน Chrome ในช่วงไตรมาสที่ 2 ปี 2024 |
Private Aggregation API คืออะไร
Private Aggregation API ช่วยให้นักพัฒนาซอฟต์แวร์สร้างรายงานข้อมูลรวมจาก Protected Audience API และข้อมูลข้ามเว็บไซต์จาก Shared Storage ได้
ปัจจุบัน API นี้มีการดำเนินการ 1 รายการคือ sendHistogramReport()
แต่อาจรองรับอื่นๆ เพิ่มเติมในอนาคต การดำเนินการตามฮิสโตแกรมช่วยให้คุณรวมข้อมูลจากผู้ใช้ในแต่ละที่เก็บข้อมูล (ซึ่งรู้จักกันใน API ว่าเป็นคีย์การรวมข้อมูล) ที่คุณกำหนดได้
การเรียกฮิสโตแกรมจะรวบรวมค่าและแสดงผลรวมที่มีเสียงรบกวนในรูปแบบรายงานสรุป ตัวอย่างเช่น รายงานอาจแสดงจำนวนเว็บไซต์ที่ผู้ใช้แต่ละคนเห็นเนื้อหาของคุณ หรือพบข้อบกพร่องในสคริปต์ของบุคคลที่สาม การดำเนินการนี้ดำเนินการภายใน Worklet ของ API อื่น
ตัวอย่างเช่น ถ้าคุณเคยบันทึกข้อมูลประชากรและข้อมูลทางภูมิศาสตร์ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถใช้ Private Aggregation API เพื่อสร้างฮิสโตแกรมที่บอกจำนวนผู้ใช้ในนิวยอร์กซิตี้ที่เห็นเนื้อหาของคุณข้ามเว็บไซต์ได้โดยประมาณ หากต้องการรวบรวมข้อมูลสำหรับการวัดนี้ คุณสามารถเข้ารหัสมิติข้อมูลภูมิศาสตร์ลงในคีย์การรวม แล้วนับผู้ใช้ในค่าที่รวบรวมได้
ข้อมูลหลัก
เมื่อคุณเรียกใช้ Private Aggregation API ที่มีคีย์การรวมและค่าที่รวบรวมได้ เบราว์เซอร์จะสร้างรายงานแบบรวมได้
ระบบจะส่งรายงานที่รวบรวมได้ไปยังเซิร์ฟเวอร์ของคุณเพื่อเก็บรวบรวมและจัดกลุ่ม บริการรวบรวมข้อมูลจะประมวลผลรายงานเป็นกลุ่มในภายหลัง และสร้างรายงานสรุป
โปรดดูเอกสารข้อมูลพื้นฐานของ Private Aggregation API เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับแนวคิดหลักที่เกี่ยวข้องกับ Private Aggregation API
ความแตกต่างจากการรายงานการระบุแหล่งที่มา
Private Aggregation API จะมีความคล้ายคลึงกันหลายอย่างกับ Attribution Reporting API Attribution Reporting เป็น API แบบสแตนด์อโลนที่ออกแบบมาเพื่อวัด Conversion ในขณะที่การรวมส่วนตัวสร้างขึ้นสําหรับการวัดผลข้ามเว็บไซต์ร่วมกับ API เช่น Protected Audience API และพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน API ทั้งสองจะสร้างรายงานแบบรวมซึ่งใช้โดยแบ็กเอนด์ของบริการรวบรวมข้อมูลเพื่อสร้างรายงานสรุป
Attribution Reporting เชื่อมโยงข้อมูลที่รวบรวมจากเหตุการณ์การแสดงผลและเหตุการณ์ Conversion ซึ่งเกิดขึ้นในเวลาที่ต่างกัน การรวมส่วนตัวจะวัดเหตุการณ์แบบข้ามเว็บไซต์รายการเดียว
ทดสอบ API นี้
Private Aggregation API จะทดสอบในเครื่องได้โดยเปิดใช้ Flag การทดสอบ Privacy Sandbox API ที่ chrome://flags/#privacy-sandbox-ads-apis
อ่านเพิ่มเติมเกี่ยวกับการทดสอบในการทดสอบและการเข้าร่วม
ใช้การสาธิต
คุณสามารถเข้าถึงการสาธิต Private Aggregation API สำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้ที่ goo.gle/shared-storage-demo และดูโค้ดได้ที่ GitHub เดโมนี้จะนำการดำเนินการฝั่งไคลเอ็นต์ไปใช้และสร้างรายงานที่รวบรวมได้ซึ่งจะส่งไปยังเซิร์ฟเวอร์ของคุณ
ในอนาคต เราจะเผยแพร่การสาธิต Private Aggregation API สำหรับ Protected Audience API
Use Case
การรวมส่วนตัวเป็น API อเนกประสงค์สำหรับการวัดข้ามเว็บไซต์ และพร้อมใช้งานใน Worklet พื้นที่เก็บข้อมูลที่ใช้ร่วมกันและ Protected Audience API ขั้นตอนแรกคือการเลือกข้อมูลที่ต้องการเก็บรวบรวม จุดข้อมูลเหล่านั้นคือพื้นฐานของคีย์การรวม
มีพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
พื้นที่เก็บข้อมูลที่ใช้ร่วมกันช่วยให้คุณอ่านและเขียนข้อมูลข้ามเว็บไซต์ในสภาพแวดล้อมที่ปลอดภัยได้เพื่อป้องกันการรั่วไหล และ Private Aggregation API จะช่วยให้คุณวัดข้อมูลข้ามเว็บไซต์ที่เก็บไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้
การวัด Unique Reach
คุณอาจต้องวัดจำนวนผู้ใช้ที่ไม่ซ้ำที่เห็นเนื้อหาของตน Private Aggregation API จะตอบคำถามได้ เช่น "ผู้ใช้ที่ไม่ซ้ำประมาณ 317 รายที่เห็น Content ID 861"
คุณสามารถตั้งค่าสถานะในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่อระบุว่าผู้ใช้เคยเห็นเนื้อหานั้นแล้วหรือไม่ ในการเข้าชมครั้งแรกที่ไม่มี Flag จะมีการเรียกใช้ Private Aggregation จากนั้นจึงมีการตั้งค่าสถานะ ในการเข้าชมที่ตามมาของผู้ใช้ ซึ่งรวมถึงการเข้าชมข้ามเว็บไซต์ คุณสามารถตรวจสอบพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและข้ามการส่งรายงานไปยังการรวมส่วนตัวได้หากมีการตั้งค่าสถานะไว้
การวัดข้อมูลประชากร
คุณอาจต้องการวัดข้อมูลประชากรของผู้ใช้ที่ดูเนื้อหาในเว็บไซต์ต่างๆ
การรวมข้อมูลส่วนตัวสามารถให้คำตอบได้ เช่น "ผู้ใช้ที่ไม่ซ้ำประมาณ 317 คนมีอายุ 18-45 ปีและมาจากเยอรมนี" ใช้พื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่อเข้าถึงข้อมูลประชากรจากบริบทของบุคคลที่สาม ในภายหลัง คุณสามารถสร้างรายงานด้วยการรวมส่วนตัวได้โดยการเข้ารหัสมิติข้อมูลกลุ่มอายุและประเทศในคีย์การรวม
การวัดความถี่ K+
คุณอาจต้องการวัดจำนวนผู้ใช้ที่ดูเนื้อหาหรือโฆษณาอย่างน้อย K ครั้งในเบราว์เซอร์หนึ่งๆ สำหรับค่า K ที่เลือกไว้ล่วงหน้า
การรวมแบบส่วนตัวให้คำตอบได้ เช่น "ผู้ใช้ประมาณ 89 คนเห็น Content ID 581 อย่างน้อย 3 ครั้ง" โดยตัวนับสามารถเพิ่มขึ้นในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจากเว็บไซต์ต่างๆ และอ่านภายในเวิร์กเลตได้ เมื่อมีจำนวนถึง K แล้ว ระบบจะส่งรายงานผ่านการรวมส่วนตัว
เมื่อใช้ Protected Audience API
Protected Audience API เปิดใช้การกำหนดเป้าหมายใหม่และกรณีการใช้งานกลุ่มเป้าหมายที่กำหนดเอง ส่วน Private Aggregation ช่วยให้คุณรายงานเหตุการณ์จาก Worklet ผู้ซื้อและผู้ขายได้ คุณสามารถใช้ API สำหรับงานต่างๆ เช่น วัดการกระจายราคาเสนอในการประมูล
จาก Worklet Protected Audience API คุณจะรวบรวมข้อมูลได้โดยตรงโดยใช้ sendHistogramReport()
และรายงานข้อมูลตามทริกเกอร์โดยใช้ reportContributionForEvent()
ซึ่งเป็นส่วนขยายพิเศษสำหรับ 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 this.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 this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
ตัวอย่างโค้ดด้านบนจะเรียก Private Aggregation เมื่อมีการโหลดเนื้อหา iframe แบบข้ามเว็บไซต์ โค้ด iframe จะโหลดเวิร์กเลต และเวิร์กเลตเรียกใช้ Private Aggregation API ที่มี Content ID ที่แปลงเป็นคีย์การรวม (ที่เก็บข้อมูล)
contributeToHistogramOnEvent()
ภายในเวิร์กเลตของ Protected Audience API เท่านั้น เรามีกลไกแบบอิงตามทริกเกอร์สำหรับส่งรายงานเฉพาะเมื่อมีเหตุการณ์บางอย่างเกิดขึ้น ฟังก์ชันนี้ยังช่วยให้ที่เก็บข้อมูลและค่าขึ้นอยู่กับสัญญาณที่ยังไม่พร้อมใช้งานในจุดดังกล่าวในการประมูล
เมธอด privateAggregation.reportContributionForEvent(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()
แม้ว่าคุกกี้ของบุคคลที่สามจะยังคงใช้งานได้ แต่เราจะมีกลไกชั่วคราวที่ช่วยให้แก้ไขข้อบกพร่องและทดสอบได้ง่ายขึ้นด้วยการเปิดใช้โหมดแก้ไขข้อบกพร่อง รายงานแก้ไขข้อบกพร่องมีประโยชน์ในการเปรียบเทียบการวัดที่อิงกับคุกกี้กับการวัด Private Aggregation และยังช่วยให้ตรวจสอบการผสานรวม API ได้อย่างรวดเร็วอีกด้วย
การเรียกใช้ privateAggregation.enableDebugMode()
ในเวิร์กเลตจะเปิดใช้โหมดแก้ไขข้อบกพร่องซึ่งทำให้รายงานที่รวบรวมข้อมูลได้รวมเพย์โหลดที่ไม่เข้ารหัส (cleartext) จากนั้นคุณจะประมวลผลเพย์โหลดเหล่านี้ได้โดยใช้เครื่องมือทดสอบในเครื่องของ Aggregation Service
โหมดแก้ไขข้อบกพร่องใช้ได้กับผู้โทรที่ได้รับอนุญาตให้เข้าถึงคุกกี้ของบุคคลที่สามเท่านั้น หากผู้โทรไม่มีสิทธิ์เข้าถึงคุกกี้ของบุคคลที่สาม 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) });
รายงานการยืนยัน
สำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถยืนยันว่ารายงานที่รวบรวมได้ที่คุณได้รับนั้นถูกต้องโดยเพิ่มรหัสบริบทในการเรียกใช้พื้นที่เก็บข้อมูลที่แชร์ ระบบจะแนบรหัสดังกล่าวไปกับรายงานที่ส่ง และในภายหลังคุณจะใช้รหัสดังกล่าวเพื่อยืนยันว่ารายงานส่งมาจากการดำเนินการพื้นที่เก็บข้อมูลที่แชร์ได้
ฟีเจอร์นี้มีพร้อมสำหรับการทดสอบใน Chrome M114 ขึ้นไป การยืนยันรายงานสำหรับ Protected Audience API ยังไม่พร้อมให้บริการสำหรับการทดสอบ
ดูข้อมูลเพิ่มเติมได้ในคำอธิบายการยืนยันรายงาน
มีส่วนร่วมและแชร์ความคิดเห็น
Private Aggregation API อยู่ระหว่างการหารือและอาจมีการเปลี่ยนแปลงในอนาคต หากคุณลองใช้ API นี้และมีความคิดเห็น เรายินดีรับฟังความคิดเห็นจากคุณ
- GitHub: อ่านผู้อธิบาย ตั้งคำถามและร่วมอภิปราย
- การสนับสนุนนักพัฒนาแอป: ถามคำถามและเข้าร่วมการสนทนาเกี่ยวกับที่เก็บการสนับสนุนนักพัฒนาแอป Privacy Sandbox
- เข้าร่วมกลุ่ม Shared Storage API และกลุ่ม Protected Audience API เพื่อดูประกาศล่าสุดที่เกี่ยวข้องกับการรวมส่วนตัว