ภาพรวม Private Aggregation API

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

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

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

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 นี้และมีความคิดเห็น เรายินดีรับฟัง

• GitHub: อ่านวิดีโออธิบาย ตั้งคำถามและเข้าร่วมการสนทนา
• การสนับสนุนนักพัฒนาแอป: ถามคำถามและเข้าร่วมการสนทนาในที่เก็บการสนับสนุนนักพัฒนาซอฟต์แวร์ของ Privacy Sandbox
• เข้าร่วมกลุ่ม Shared Storage API และกลุ่ม Protected Audience API เพื่อดูประกาศล่าสุดที่เกี่ยวข้องกับการรวบรวมข้อมูลส่วนตัว