พื้นฐาน Private Aggregation API

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

เอกสารนี้จัดทำขึ้นสำหรับใคร

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

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

คำสำคัญ

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

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

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

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

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

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

คีย์การรวม

คีย์การรวม ("key" เรียกสั้นๆ ว่า) แสดงถึงที่เก็บข้อมูลที่ฟังก์ชัน ระบบจะสะสมค่าที่รวมได้ มิติข้อมูลสามารถเข้ารหัสได้อย่างน้อย 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

ภายในเวิร์กเล็ตพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถเข้าถึง 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 คนที่เห็น Widget ID 3276 ของฉัน จากฝรั่งเศส" ค่าที่รวบรวมได้คือ 1 สําหรับผู้ใช้แต่ละราย และ "ผู้ใช้ 4, 881 ราย" เท่ากับ ค่ารวมซึ่งเป็นผลรวมของค่าที่รวบรวมได้ทั้งหมดสําหรับรายการนั้น คีย์การรวมข้อมูล

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

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

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

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

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

งบประมาณการสนับสนุนจะแสดงด้วยพารามิเตอร์ L₁ และเป็น ตั้งค่าเป็น 2¹⁶ (65,536) ต่อ 10 นาทีต่อวัน โดยมี 2²⁰ ครั้ง

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

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

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

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

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

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

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

  "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 หน้า:

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

รวบรวมและรายงานที่รวบรวมได้เป็นกลุ่ม

เบราว์เซอร์จะส่งรายงานที่รวบรวมได้ไปยังต้นทางของ Worklet ที่มีการเรียกไปยัง 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

รายงานสรุป

รายงานสรุป ช่วยให้คุณเห็นข้อมูลที่รวบรวมพร้อม การเพิ่มสัญญาณรบกวน คุณสามารถขอ รายงานสรุปสำหรับชุดคีย์ที่กำหนด

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

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

เช่น

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

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

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

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

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

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

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

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

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

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

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

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