ภาพรวม Private Aggregation API

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

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

สถานะการใช้งาน

建议 状态
使用共享存储空间的报告验证功能防止出现无效的 Private Aggregation API 报告
说明
适用于 Chrome
不公开汇总调试模式的可用性取决于第三方的资格条件
GitHub 问题
适用于 Chrome M119
缩短报告延迟时间
说明
适用于 Chrome M119
对 Private Aggregation API 和 Google Cloud 汇总服务的支持
说明
在 Chrome M121 中提供
可汇总报告载荷的内边距
说明
适用于 Chrome M119
为 challengeReportBuyers 报告提供的不公开汇总调试模式
说明
预计会在 Chrome M123 中推出
对过滤 ID 的支持
说明
预计于 2024 年第 2 季度在 Chrome 中首次推出。

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

ตั้งค่าการทดสอบ Privacy Sandbox API เป็นเปิดใช้เพื่อใช้ API เหล่านี้
ตั้งค่าการทดสอบ Privacy Sandbox Ads API ให้เปิดใช้เพื่อใช้ API เหล่านี้

อ่านเพิ่มเติมเกี่ยวกับการทดสอบในการทดสอบและการเข้าร่วม

ใช้การสาธิต

คุณสามารถเข้าถึงการสาธิต 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 นี้และมีความคิดเห็น เรายินดีรับฟังความคิดเห็นจากคุณ