พื้นฐาน Private Aggregation API

แนวคิดหลักของ Private Aggregation API

เอกสารนี้มีไว้สำหรับใคร

Private Aggregation API จะเปิดใช้การรวบรวมข้อมูลรวมจาก Worklet ที่มีสิทธิ์เข้าถึงข้อมูลข้ามเว็บไซต์ แนวคิดที่แชร์ไว้นี้สำคัญต่อนักพัฒนาแอปที่สร้างฟังก์ชันการรายงานภายในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและ Protected Audience API

  • หากคุณเป็นนักพัฒนาแอปที่สร้างระบบการรายงานเพื่อการวัดผลข้ามเว็บไซต์
  • หากคุณเป็นนักการตลาด นักวิทยาศาสตร์ข้อมูล หรือผู้บริโภครายงานสรุปรายอื่นๆ การทําความเข้าใจกลไกเหล่านี้จะช่วยให้คุณตัดสินใจเกี่ยวกับการออกแบบเพื่อเรียกดูรายงานสรุปที่เพิ่มประสิทธิภาพได้

คำสำคัญ

ก่อนอ่านเอกสารนี้ เราขอแนะนำให้ทำความคุ้นเคยกับ คำและแนวคิดสำคัญต่างๆ คำศัพท์แต่ละคำเหล่านี้จะอธิบายโดยละเอียดที่นี่

  • คีย์การรวม (หรือที่เรียกว่าที่เก็บข้อมูล) คือคอลเล็กชันของจุดข้อมูลที่กำหนดไว้ล่วงหน้า เช่น คุณอาจต้องการรวบรวมที่เก็บข้อมูลตำแหน่งที่เบราว์เซอร์รายงานชื่อประเทศ คีย์การรวมอาจมีมิติข้อมูลมากกว่า 1 รายการ (เช่น ประเทศและรหัสของวิดเจ็ตเนื้อหา)
  • ค่าแบบรวมได้คือจุดข้อมูลแต่ละจุดที่รวบรวมไว้ในคีย์การรวม หากต้องการวัดจํานวนผู้ใช้จากฝรั่งเศสที่เห็นเนื้อหาของคุณ France จะเป็นมิติข้อมูลในคีย์การรวม และ viewCount ของ 1 คือค่าที่รวบรวมได้
  • รายงานที่รวบรวมได้จะได้รับการสร้างและเข้ารหัสภายในเบราว์เซอร์ สำหรับ Private Aggregation API จะมีข้อมูลเกี่ยวกับเหตุการณ์เดียว
  • บริการรวบรวมข้อมูลจะประมวลผลข้อมูลจากรายงานที่รวบรวมได้เพื่อสร้างรายงานสรุป
  • รายงานสรุปคือผลลัพธ์สุดท้ายของบริการรวบรวม และมีข้อมูลผู้ใช้ที่รวบรวมจากเสียงรบกวนและข้อมูล Conversion แบบละเอียด
  • เวิร์กเล็ตเป็นโครงสร้างพื้นฐานที่ช่วยให้คุณเรียกใช้ฟังก์ชัน JavaScript หนึ่งๆ และส่งคืนข้อมูลกลับไปยังผู้ส่งคำขอได้ ภายใน Worklet คุณสามารถเรียกใช้ JavaScript ได้ แต่จะโต้ตอบหรือสื่อสารกับหน้าภายนอกไม่ได้

เวิร์กโฟลว์การรวมส่วนตัว

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

ข้อมูลจะส่งจากไคลเอ็นต์ไปยังผู้รวบรวมข้อมูล จากนั้นไปยังบริการรวบรวมข้อมูลเพื่อสร้างรายงานสรุป
  1. เมื่อคุณเรียกใช้ Private Aggregation API ไคลเอ็นต์ (เบราว์เซอร์) จะสร้างและส่งรายงานที่รวบรวมได้ไปยังเซิร์ฟเวอร์เพื่อเก็บรวบรวม
  2. เซิร์ฟเวอร์ของคุณจะรวบรวมรายงานจากไคลเอ็นต์และจัดเป็นกลุ่มเพื่อส่งไปยังบริการรวบรวมข้อมูล
  3. เมื่อรวบรวมรายงานได้เพียงพอแล้ว คุณจะจัดกลุ่มและส่งรายงานนั้นไปยัง บริการรวบรวมข้อมูล ซึ่งทำงานในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้เพื่อสร้างรายงานสรุป

เวิร์กโฟลว์ที่อธิบายในส่วนนี้คล้ายกับ Attribution Reporting API อย่างไรก็ตาม การรายงานการระบุแหล่งที่มาจะเชื่อมโยงข้อมูลที่รวบรวมจากเหตุการณ์การแสดงผลและเหตุการณ์ Conversion ซึ่งเกิดขึ้นในเวลาที่ต่างกัน การรวมแบบส่วนตัวจะวัดเหตุการณ์แบบข้ามเว็บไซต์รายการเดียว

คีย์การรวม

คีย์การรวม (เรียกสั้นๆ ว่า "คีย์") แสดงถึงที่เก็บข้อมูลซึ่งจะสะสมค่าที่รวบรวมได้ มิติข้อมูลอย่างน้อย 1 รายการสามารถเข้ารหัส เป็นคีย์ได้ มิติข้อมูลแสดงถึงแง่มุมบางอย่างที่คุณต้องการข้อมูลเชิงลึกเพิ่มเติม เช่น กลุ่มอายุของผู้ใช้ หรือจำนวนการแสดงผลของแคมเปญโฆษณา

ตัวอย่างเช่น คุณอาจมีวิดเจ็ตที่ฝังอยู่ในหลายเว็บไซต์และต้องการวิเคราะห์ประเทศของผู้ใช้ที่เห็นวิดเจ็ตของคุณ คุณกำลังตอบคำถามต่างๆ เช่น "มีผู้ใช้ที่เห็นวิดเจ็ตของฉันกี่คน มาจากประเทศ X" หากต้องการรายงานเกี่ยวกับคำถามนี้ คุณสามารถตั้งค่าคีย์การรวมที่เข้ารหัสมิติข้อมูล 2 รายการ ได้แก่ รหัสวิดเจ็ตและรหัสประเทศ

คีย์ที่ส่งไปยัง Private Aggregation API คือ BigInt ซึ่งประกอบด้วยมิติข้อมูลหลายรายการ ในตัวอย่างนี้ มิติข้อมูลคือ รหัสวิดเจ็ตและรหัสประเทศ สมมติว่ารหัสวิดเจ็ตมีความยาวได้สูงสุด 4 หลัก เช่น 1234 และแต่ละประเทศจะจับคู่กับตัวเลขที่เรียงตามลำดับตัวอักษร เช่น อัฟกานิสถานคือ 1 ฝรั่งเศสคือ 61 และซิมบับเวคือ "195" ดังนั้นคีย์แบบรวมได้ยาว 7 หลัก โดยสงวนอักขระ 4 ตัวแรกไว้สำหรับ WidgetID และสงวนอักขระ 3 ตัวสุดท้ายไว้สำหรับ CountryID

สมมติว่าคีย์แสดงจำนวนผู้ใช้จากฝรั่งเศส (รหัสประเทศ 061) ที่เห็นรหัสวิดเจ็ต 3276 คีย์การรวมคือ 3276061

คีย์การรวม
รหัสวิดเจ็ต รหัสประเทศ
3276 061

คีย์การรวมยังสร้างได้ด้วยกลไกการแฮช เช่น SHA-256 เช่น สตริง {"WidgetId":3276,"CountryID":67} สามารถแฮชแล้วแปลงเป็นค่า BigInt ที่ 42943797454801331377966796057547478208888578253058197330928948081739249096287n หากค่าแฮชมีมากกว่า 128 บิต คุณสามารถตัดค่าดังกล่าวเพื่อไม่ให้เกินค่าของที่เก็บข้อมูลสูงสุดที่อนุญาตที่ 2^128−1

ภายใน Worklet Shared Storage คุณจะเข้าถึงโมดูล crypto และ TextEncoder ที่จะช่วยสร้างแฮชได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างแฮชได้ที่ SubtleCrypto.digest() ใน MDN

ตัวอย่างต่อไปนี้อธิบายวิธีสร้างคีย์ที่เก็บข้อมูลจากค่าที่แฮช

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

ค่ารวมได้

ระบบจะรวมค่าที่รวบรวมได้ตามคีย์จากผู้ใช้จำนวนมากเพื่อสร้างข้อมูลเชิงลึกแบบรวมในรูปแบบค่าสรุปในรายงานสรุป

กลับมาที่ตัวอย่างคำถามที่เคยโพสต์ไว้ว่า "มีผู้ใช้ที่เห็นวิดเจ็ตของฉันมาจากฝรั่งเศสกี่คน" คำตอบสำหรับคำถามนี้จะมีลักษณะดังนี้ "ผู้ใช้ประมาณ 4,881 คนที่เห็นรหัสวิดเจ็ต 3276 ของฉันมาจากฝรั่งเศส" ค่ารวมได้คือ 1 สำหรับผู้ใช้แต่ละราย และ "ผู้ใช้ 4881" เป็นค่ารวมที่เป็นผลรวมของค่าที่รวบรวมได้ทั้งหมดสำหรับคีย์การรวมดังกล่าว

คีย์การรวม ค่ารวมได้
รหัสวิดเจ็ต รหัสประเทศ จำนวนการดู
3276 061 1

ในตัวอย่างนี้ เราจะเพิ่มค่าขึ้น 1 ค่าสำหรับแต่ละผู้ใช้แต่ละคนที่เห็นวิดเจ็ต ในทางปฏิบัติ คุณสามารถปรับขนาดค่าแบบรวมได้เพื่อปรับปรุงอัตราส่วนสัญญาณต่อสัญญาณรบกวน

งบประมาณการมีส่วนร่วม

การเรียก Private Aggregation API แต่ละครั้งจะเรียกว่าการมีส่วนร่วม ระบบจำกัดจำนวนการมีส่วนร่วมที่รวบรวมได้จากผู้ใช้แต่ละรายเพื่อปกป้องความเป็นส่วนตัวของผู้ใช้

เมื่อคุณรวมค่าทั้งหมดที่รวมได้ทั้งหมดในคีย์การรวมทั้งหมดแล้ว ผลรวมจะต้องน้อยกว่างบประมาณการมีส่วนร่วม งบประมาณจะกำหนดขอบเขตต่อเวิร์กเล็ต ต้นทาง ต่อวัน และแยกกันสำหรับ Protected Audience API และ Worklet พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ระบบจะใช้หน้าต่างแบบเลื่อนไปเรื่อยๆ ในช่วง 24 ชั่วโมงที่ผ่านมาโดยประมาณสำหรับวันนั้นๆ หากรายงานแบบรวมใหม่ได้จะทำให้ใช้งบประมาณเกิน ระบบจะไม่สร้างรายงานนั้น

งบประมาณการมีส่วนร่วมจะแสดงด้วยพารามิเตอร์ L1 และกำหนดเป็น 216 (65,536) ต่อ 10 นาทีต่อวัน โดยมี Backstop อยู่ที่ 220

(1,048,576) ดูคำอธิบายเพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์เหล่านี้

มูลค่าของงบประมาณการสนับสนุนสามารถกำหนดเองได้ แต่จะมีการปรับสเกลข้อผิดพลาดตามนั้น คุณสามารถใช้งบประมาณนี้เพื่อเพิ่มอัตราส่วนสัญญาณต่อสัญญาณรบกวนในค่าสรุปให้สูงสุด (เราจะอธิบายเพิ่มเติมในส่วนเสียงรบกวนและการปรับขนาด)

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับงบประมาณการสนับสนุน โปรดดูคำอธิบาย และดูคำแนะนำเพิ่มเติมในงบประมาณการมีส่วนร่วม

รายงานที่รวบรวมได้

เมื่อผู้ใช้เรียกใช้ Private Aggregation API เบราว์เซอร์จะสร้างรายงานที่รวบรวมได้ซึ่งบริการรวมจะประมวลผลในภายหลังเพื่อสร้างรายงานสรุป รายงานที่รวบรวมได้จะอยู่ในรูปแบบ JSON และมีรายการการมีส่วนร่วมที่เข้ารหัส โดยแต่ละรายการเป็นคู่ {aggregation key, aggregatable value} ระบบจะส่งรายงานที่รวบรวมได้ซึ่งจะมีความล่าช้าแบบสุ่มสูงสุด 1 ชั่วโมง

ข้อมูลเหล่านั้นจะได้รับการเข้ารหัสและอ่านนอกบริการรวบรวมข้อมูลไม่ได้ บริการรวบรวมข้อมูลจะถอดรหัสรายงานและสร้างรายงานสรุป ผู้ประสานงานจะเป็นผู้ออกคีย์การเข้ารหัสสำหรับเบราว์เซอร์และคีย์การถอดรหัสสำหรับบริการ Aggregation ซึ่งทำหน้าที่เป็นบริการการจัดการคีย์ ผู้ประสานงานจะเก็บรายการแฮชไบนารีของอิมเมจบริการไว้เพื่อยืนยันว่าผู้โทรได้รับอนุญาตให้รับคีย์การถอดรหัส

ตัวอย่างรายงานแบบรวมที่เปิดใช้โหมดแก้ไขข้อบกพร่องได้

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

โดยคุณจะตรวจสอบรายงานที่รวบรวมได้จากหน้า chrome://private-aggregation-internals ดังนี้

ภาพหน้าจอของหน้าภายในของ Private Aggregation API

สำหรับวัตถุประสงค์ในการทดสอบ คุณสามารถใช้ปุ่ม "ส่งรายงานที่เลือก" เพื่อส่งรายงานไปยังเซิร์ฟเวอร์ได้ทันที

รวบรวมและจัดกลุ่มรายงานที่รวบรวมได้

เบราว์เซอร์จะส่งรายงานที่รวบรวมได้ไปยังต้นทางของเวิร์กเล็ตที่มีการเรียกใช้ Private Aggregation API โดยใช้เส้นทางที่รู้จักกันดีในรายการ

  • สำหรับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน: /.well-known/private-aggregation/report-shared-storage
  • สำหรับ Protected Audience /.well-known/private-aggregation/report-protected-audience

ที่ปลายทางเหล่านี้ คุณจะต้องใช้งานเซิร์ฟเวอร์ (ซึ่งทำหน้าที่เป็นผู้รวบรวม) ที่รับรายงานที่รวบรวมได้ซึ่งส่งมาจากไคลเอ็นต์

จากนั้นเซิร์ฟเวอร์ควรจัดกลุ่มรายงานและส่งกลุ่มไปยังบริการรวบรวมข้อมูล สร้างกลุ่มตามข้อมูลที่มีอยู่ในเพย์โหลดที่ไม่ได้เข้ารหัสของรายงานที่รวบรวมได้ เช่น ช่อง shared_info ตามหลักการแล้ว กลุ่มควรมีรายงาน 100 รายการขึ้นไปต่อกลุ่ม

คุณเลือกที่จะจัดกลุ่มเป็นรายวันหรือรายสัปดาห์ก็ได้ กลยุทธ์นี้มีความยืดหยุ่นและคุณสามารถเปลี่ยนกลยุทธ์แบบกลุ่มสำหรับเหตุการณ์เฉพาะที่คุณคาดว่าจะมีปริมาณเพิ่มขึ้นได้ เช่น วันที่คาดว่าจะมีการแสดงผลมากขึ้น กลุ่มควรมีรายงานจาก API เวอร์ชันเดียวกัน ต้นทางการรายงาน และกำหนดเวลารายงาน

บริการรวบรวม

บริการจะทำงานใน TEE โดยถอดรหัสรายงานที่รวบรวมได้และเพิ่มสัญญาณรบกวนเพื่อสร้างรายงานสรุปขั้นสุดท้าย

บริการรวบรวมข้อมูลจะได้รับรายงานที่รวบรวมได้ที่เข้ารหัสจากผู้รวบรวมข้อมูลและสร้างรายงานสรุป

หากต้องการถอดรหัสเพย์โหลดรายงาน บริการรวบรวมจะดึงคีย์การถอดรหัสจากผู้ประสานงาน บริการนี้ทำงานในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ (TEE) ซึ่งทำให้มั่นใจได้ถึงความสมบูรณ์ของข้อมูล การรักษาข้อมูลที่เป็นความลับ และความสมบูรณ์ของโค้ด แม้ว่าคุณจะเป็นเจ้าของและเป็นผู้ดำเนินการบริการ แต่คุณจะมองไม่เห็นข้อมูลที่กำลังประมวลผลภายใน TEE

รายงานสรุป

รายงานสรุป ช่วยให้คุณเห็นข้อมูลที่คุณรวบรวมได้โดยการใส่เสียงรบกวน คุณขอรายงานสรุปสำหรับชุดคีย์หนึ่งๆ ได้

รายงานสรุปประกอบด้วยชุดคู่คีย์-ค่าในรูปแบบพจนานุกรม JSON แต่ละคู่มีข้อมูลต่อไปนี้

  • bucket: คีย์การรวมเป็นสตริงตัวเลขฐานสอง หากคีย์การรวมที่ใช้คือ "123" ที่เก็บข้อมูลจะเป็น "1111011"
  • value: ค่าสรุปสําหรับเป้าหมายการวัดผลหนึ่งๆ สรุปจากรายงานที่รวบรวมได้ทั้งหมดที่มีการเพิ่มสัญญาณรบกวน

เช่น

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

เสียงรบกวนและการปรับขนาด

เพื่อรักษาความเป็นส่วนตัวของผู้ใช้ บริการรวบรวมข้อมูลจะเพิ่มสัญญาณรบกวน 1 ครั้งลงในค่าสรุปแต่ละค่าทุกครั้งที่มีการขอรายงานสรุป ค่าสัญญาณรบกวนจะสุ่มมาจากการแจกแจงความน่าจะเป็นของ Laplace แม้ว่าคุณจะไม่สามารถควบคุมการเพิ่มสัญญาณรบกวนได้โดยตรง แต่คุณก็อาจส่งผลต่อข้อมูลการวัดผลได้

การกระจายสัญญาณรบกวนจะเท่ากันโดยไม่คำนึงถึงผลรวมของค่าแบบรวมทั้งหมด ดังนั้น ยิ่งค่าที่รวบรวมได้สูงเท่าไร ก็ยิ่งมีแนวโน้มที่จะเกิดผลกระทบต่อผลลัพธ์น้อยลงเท่านั้น

เช่น สมมติว่าการกระจายเสียงรบกวนมีค่าเบี่ยงเบนมาตรฐานเป็น 100 และจัดกึ่งกลางที่ 0 หากค่ารายงานแบบสรุปรวมที่เก็บรวบรวมได้ (หรือ "ค่ารวมได้") เท่ากับ 200 เท่านั้น ค่าเบี่ยงเบนมาตรฐานของสัญญาณรบกวนจะเป็น 50% ของค่ารวม แต่ถ้าค่ารวมได้คือ 20,000 ค่าเบี่ยงเบนมาตรฐานของ Noise จะเป็นเพียง 0.5% ของค่ารวม ดังนั้น ค่ารวมที่ 20,000 จะมีอัตราส่วนสัญญาณต่อสัญญาณรบกวนที่สูงกว่ามาก

ดังนั้น การคูณค่ารวมด้วยค่าตัวคูณมาตราส่วนจะช่วยลดสัญญาณรบกวนได้ ค่าตัวคูณมาตราส่วนจะแสดงถึงจำนวนที่คุณต้องการปรับขนาดค่าที่รวบรวมได้ที่กำหนด

สัญญาณรบกวนเป็นค่าคงที่โดยไม่คำนึงถึงค่ารวม

การปรับขนาดค่าให้สูงขึ้นโดยการเลือกปัจจัยการปรับสเกลที่ใหญ่ขึ้นจะลดเสียงรบกวนที่เกี่ยวข้อง อย่างไรก็ตาม การดำเนินการนี้จะทำให้ยอดรวมการมีส่วนร่วมทั้งหมดในที่เก็บข้อมูลทั้งหมดถึงขีดจำกัดเร็วขึ้นด้วย การปรับขนาดค่าลดลงโดยเลือกปัจจัยการปรับขนาดที่เล็กลงอย่างสม่ำเสมอจะเพิ่มสัญญาณรบกวนที่เกี่ยวข้อง แต่จะช่วยลดความเสี่ยงในการใช้งบประมาณถึงขีดจำกัด

ปรับขนาดค่ารวมได้กับงบประมาณการสนับสนุน

หากต้องการคำนวณปัจจัยการปรับขนาดที่เหมาะสม ให้แบ่งงบประมาณการสนับสนุนด้วยผลรวมสูงสุดของค่าที่รวบรวมได้ในทุกคีย์

ดูเอกสารเกี่ยวกับงบประมาณการมีส่วนร่วมเพื่อดูข้อมูลเพิ่มเติม

มีส่วนร่วมและแชร์ความคิดเห็น

Private Aggregation API อยู่ระหว่างการหารือและอาจมีการเปลี่ยนแปลงในอนาคต หากคุณลองใช้ API นี้และมีความคิดเห็น เรายินดีรับฟังความคิดเห็นจากคุณ