ภาพรวม Private Aggregation API

สร้างรายงานข้อมูลรวมโดยใช้ข้อมูลจาก Protected Audience และข้อมูลข้ามเว็บไซต์จากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

ในการมอบฟีเจอร์สำคัญที่เว็บใช้ การรวบรวมแบบส่วนตัว API ได้สร้างขึ้นสำหรับการรวมและรายงานเกี่ยวกับข้อมูลแบบข้ามเว็บไซต์ใน วิธีการรักษาความเป็นส่วนตัว

สถานะการติดตั้งใช้งาน

提案 状态
通过共享存储空间的报告验证防止无效的 Private Aggregation API 报告
说明者		 在 Chrome 中提供
不公开汇总调试模式的可用性取决于第三方 Cookie 的使用资格
GitHub 问题		 适用于 Chrome M119
缩短报告延迟时间
说明		 适用于 Chrome M119
支持 Google Cloud 专用汇总 API 和汇总服务
说明		 适用于 Chrome M121
可汇总报告载荷的填充
说明		 适用于 Chrome M119
私密汇总调试模式适用于 auctionReportBuyers 报告
说明		 适用于 Chrome M123
支持过滤 ID
解说		 适用于 Chrome M128
客户端贡献合并
解说		 适用于 Chrome M129

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 แล้ว คุณจะส่งรายงานผ่านการรวมข้อมูลแบบส่วนตัวได้

การระบุแหล่งที่มาแบบมัลติทัช

เราจะเผยแพร่คำแนะนำนี้ในเว็บไซต์สำหรับนักพัฒนาซอฟต์แวร์เพื่อให้เทคโนโลยีโฆษณาเข้าใจวิธีใช้ MTA ภายในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน + การรวมข้อมูลส่วนตัว

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

โหมดแก้ไขข้อบกพร่องมีไว้สำหรับผู้เรียกที่ได้รับอนุญาตให้เข้าถึงคุกกี้ของบุคคลที่สามเท่านั้น หากผู้โทรไม่มีสิทธิ์เข้าถึงคุกกี้ของบุคคลที่สาม 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 นี้และมีความคิดเห็น เรายินดีรับฟัง