ภาพรวม Private Aggregation API

สร้างรายงานข้อมูลรวมโดยใช้ข้อมูลจาก 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

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