หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

กลุ่มเป้าหมาย: ผู้ให้บริการเทคโนโลยีโฆษณาและการวัดผล

ลองใช้เดโม

ลองใช้การสาธิตการใช้งานจริง ทำตามขั้นตอนในคำแนะนำการสาธิตเพื่อเปิดใช้ Privacy Sandbox API การเปิด Chrome DevTools ช่วยให้คุณเห็นภาพผลลัพธ์ของกรณีการใช้งานต่างๆ Use Case ที่มีในการสาธิต

การรวบรวมข้อมูลแบบส่วนตัว
- การวัด Unique Reach
- การวัดข้อมูลประชากร
- การวัดความถี่ K+
การใช้งานทั่วไป
- วัดเหตุการณ์โฮเวอร์โอเวอร์ภายในเฟรมที่มีการปิดกั้น
- การนำทางระดับบนสุด
- การควบคุมตำแหน่งที่บุคคลที่สามสามารถเขียนได้

วิธีดูพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

หากต้องการดูข้อมูลที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ให้ใช้เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome คุณจะดูข้อมูลที่จัดเก็บไว้ได้ใน Application -> Shared Storage

ดูข้อมูลที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันโดยใช้เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome

ดูรายงานสำหรับการรวบรวมข้อมูลส่วนบุคคล

หากต้องการดูรายงานแบบรวมที่ส่งได้ ให้ไปที่ chrome://private-aggregation-internals เมื่อเปิดใช้โหมดแก้ไขข้อบกพร่อง ระบบจะส่งรายงาน (โดยไม่ล่าช้า) ไปยัง [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage พร้อมกับรายงานการหน่วงเวลาที่จะส่งไปที่ [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage

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

ดูรายงานใน chrome://private-aggregation-internals

API พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

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

พื้นที่เก็บข้อมูลที่ใช้ร่วมกันจะจำกัดไว้เฉพาะต้นทางบริบท (ผู้เรียกใช้ sharedStorage)

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

เรียกใช้พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

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

การใช้ JavaScript เทคโนโลยีโฆษณาสามารถใช้ฟังก์ชันพื้นที่เก็บข้อมูลที่ใช้ร่วมกันที่เฉพาะเจาะจง เช่น การตั้งค่า การต่อท้าย และการลบค่าที่อยู่นอกเวิร์กโฟลว์ JavaScript อย่างไรก็ตาม ฟังก์ชันต่างๆ เช่น การอ่านพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและการดำเนินการการรวมส่วนตัวจะต้องดำเนินการผ่านเวิร์กเล็ต JavaScript ดูเมธอดที่สามารถใช้นอกเวิร์กเล็ต JavaScript ได้ในแพลตฟอร์ม API ที่เสนอ - นอกเวิร์กเล็ต

ดูเมธอดที่ใช้ในเวิร์กเลตระหว่างการดำเนินการได้ในแพลตฟอร์ม API ที่เสนอ - ในเวิร์กเลต
การใช้ส่วนหัวการตอบกลับ

ฟีเจอร์นี้พร้อมให้บริการใน M119 แล้ว

เช่นเดียวกับ JavaScript เฉพาะฟังก์ชันบางอย่าง เช่น การตั้งค่า การเพิ่มต่อท้าย และการลบค่าในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจะทำได้โดยใช้ส่วนหัวการตอบกลับ หากต้องการใช้งานพื้นที่เก็บข้อมูลที่ใช้ร่วมกันในส่วนหัวการตอบกลับ จะต้องใส่ Shared-Storage-Writable: ?1 ไว้ในส่วนหัวของคำขอ

หากต้องการเริ่มส่งคำขอจากไคลเอ็นต์ ให้เรียกใช้โค้ดต่อไปนี้ตามวิธีการที่คุณเลือก
- ใช้ไป fetch()
```
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
```
- การใช้แท็ก iframe หรือ img
```
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
```
- การใช้แอตทริบิวต์ IDL กับแท็ก iframe หรือ img
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

ดูข้อมูลเพิ่มเติมได้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน: ส่วนหัวการตอบกลับ

กำลังเขียนไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

หากต้องการเขียนไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ให้เรียกใช้ sharedStorage.set() จากภายในหรือภายนอกเวิร์กเล็ต JavaScript หากมีการเรียกจากภายนอก Worklet ระบบจะเขียนข้อมูลไปยังต้นทางของบริบทการท่องเว็บที่เป็นต้นทางของการเรียกใช้ หากเรียกใช้จากภายใน Worklet ระบบจะเขียนข้อมูลไปยังต้นทางของบริบทการท่องเว็บที่โหลด Worklet คีย์ที่ตั้งค่าไว้จะมีวันที่หมดอายุ 30 วันนับจากวันที่อัปเดตล่าสุด

คุณจะกรอกข้อมูลในช่อง ignoreIfPresent หรือไม่ก็ได้ หากมีคีย์และตั้งค่าเป็น true คีย์จะไม่อัปเดตหากมีอยู่แล้ว วันหมดอายุของคีย์จะต่ออายุภายใน 30 วันนับจากวันที่เรียก set() แม้ว่าคีย์จะไม่อัปเดตก็ตาม

หากมีการเข้าถึงพื้นที่เก็บข้อมูลที่ใช้ร่วมกันหลายครั้งในการโหลดหน้าเว็บเดียวกันด้วยคีย์เดียวกัน ระบบจะเขียนทับค่าของคีย์นั้น ควรใช้ sharedStorage.append() หากคีย์ต้องคงค่าก่อนหน้าไว้

การใช้ JavaScript

ภายนอก Worklet:

window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
// Shared Storage: {'myKey': 'myValue2'}

ในทำนองเดียวกัน ภายใน Worklet ให้ทำดังนี้

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

การใช้ส่วนหัวการตอบกลับ

หรือคุณจะเขียนไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกันโดยใช้ส่วนหัวการตอบกลับก็ได้ โดยใช้ Shared-Storage-Write ในส่วนหัวการตอบกลับพร้อมคำสั่งต่อไปนี้
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
```
หลายรายการจะคั่นด้วยคอมมาและรวม set, append, delete และ clear ได้
```
Shared-Storage-Write : 
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
```

การต่อท้ายค่า

คุณสามารถต่อท้ายค่าลงในคีย์ที่มีอยู่ได้โดยใช้วิธีการต่อท้าย หากไม่มีคีย์ การเรียกใช้ append() จะสร้างคีย์และตั้งค่า ซึ่งทำได้โดยใช้ JavaScript หรือส่วนหัวการตอบกลับ

การใช้ JavaScript

หากต้องการอัปเดตค่าของคีย์ที่มีอยู่ ให้ใช้ sharedStorage.append() จากภายในหรือนอกเวิร์กเล็ต

window.sharedStorage.append('myKey', 'myValue1');
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.append('myKey', 'myValue2');
// Shared Storage: {'myKey': 'myValue1myValue2'}
window.sharedStorage.append('anotherKey', 'hello');
// Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}

วิธีต่อท้ายภายในเวิร์กเลต

sharedStorage.append('myKey', 'myValue1');

การใช้ส่วนหัวการตอบกลับ

คุณจะใช้ Shared-Storage-Write ในส่วนหัวการตอบกลับเพื่อส่งผ่านคู่คีย์-ค่าได้ ซึ่งคล้ายกับการตั้งค่าในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

การอ่านจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

คุณอ่านจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้จากภายใน Worklet เท่านั้น

await sharedStorage.get('mykey');

ต้นทางของบริบทการท่องเว็บที่โหลดโมดูล Worklet จากตัวกำหนดพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

กำลังลบจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

คุณดำเนินการลบจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้โดยใช้ JavaScript จากด้านในหรือนอก Worklet หรือโดยการใช้ส่วนหัวการตอบกลับด้วย delete() หากต้องการลบคีย์ทั้งหมดพร้อมกัน ให้ใช้ clear() จากตำแหน่งใดคีย์หนึ่ง

การใช้ JavaScript

หากต้องการลบพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจากภายนอก Worklet ให้ทำดังนี้
```
window.sharedStorage.delete('myKey');
```
หากต้องการลบออกจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกันจากภายใน Worklet ให้ทำดังนี้
```
sharedStorage.delete('myKey');
```
หากต้องการลบคีย์ทั้งหมดพร้อมกันจากภายนอก Worklet ให้ทำดังนี้
```
window.sharedStorage.clear();
```
หากต้องการลบคีย์ทั้งหมดพร้อมกันจากในเวิร์กเลต ให้ทำดังนี้
```
sharedStorage.clear();
```
การใช้ส่วนหัวการตอบกลับ

หากต้องการลบค่าโดยใช้ส่วนหัวการตอบกลับ คุณจะใช้ Shared-Storage-Write ในส่วนหัวการตอบกลับเพื่อส่งคีย์ที่จะลบได้ด้วย
```
delete;key="myKey"
```
หากต้องการลบคีย์ทั้งหมดโดยใช้ส่วนหัวการตอบกลับ ให้ทำดังนี้
```
clear;
```

การสลับบริบท

ระบบจะเขียนข้อมูลพื้นที่เก็บข้อมูลที่ใช้ร่วมกันลงในต้นทาง (เช่น https://example.adtech.com) ของบริบทการท่องเว็บที่เป็นต้นทางของการเรียก

เมื่อคุณโหลดโค้ดของบุคคลที่สามโดยใช้แท็ก <script> โค้ดจะทำงานในบริบทการท่องเว็บของเครื่องมือฝัง ดังนั้น เมื่อโค้ดของบุคคลที่สามเรียกใช้ sharedStorage.set() ระบบจะเขียนข้อมูลไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกันของเครื่องมือฝัง เมื่อคุณโหลดโค้ดของบุคคลที่สามภายใน iframe โค้ดจะได้รับบริบทการท่องเว็บใหม่ และต้นทางของโค้ดจะเป็นที่มาของ iframe ดังนั้น การเรียก sharedStorage.set() ที่สร้างขึ้นจาก iframe จะจัดเก็บข้อมูลลงในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันของต้นทาง iframe

บริบทของบุคคลที่หนึ่ง

หากหน้าเว็บของบุคคลที่หนึ่งฝังโค้ด JavaScript ของบุคคลที่สามที่เรียกใช้ sharedStorage.set() หรือ sharedStorage.delete() คู่คีย์-ค่าจะจัดเก็บอยู่ในบริบทของบุคคลที่หนึ่ง

ข้อมูลที่จัดเก็บไว้ในหน้าเว็บบุคคลที่หนึ่งซึ่งมี JavaScript ของบุคคลที่สามฝังอยู่

บริบทของบุคคลที่สาม

คุณจัดเก็บคู่คีย์-ค่าในเทคโนโลยีโฆษณาหรือบริบทของบุคคลที่สามได้โดยสร้าง iframe แล้วเรียกใช้ set() หรือ delete() ในโค้ด JavaScript จากภายใน iframe

ข้อมูลที่จัดเก็บในบริบทของเทคโนโลยีโฆษณาหรือบุคคลที่สาม

API การรวมส่วนตัว

หากต้องการวัดข้อมูลแบบรวมซึ่งจัดเก็บไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน คุณสามารถใช้ Private Aggregation API ได้

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

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

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

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

การใช้พื้นที่เก็บข้อมูลที่ใช้ร่วมกันและการรวมส่วนตัว

ใน iframe ของโฆษณา ให้โหลดโมดูลเวิร์กเล็ตโดยเรียกใช้ addModule() หากต้องการเรียกใช้เมธอดที่ลงทะเบียนไว้ในไฟล์ sharedStorageWorklet.js Worklet ใน JavaScript ของ iframe โฆษณาเดียวกัน ให้เรียก sharedStorage.run()

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

ในสคริปต์ Worklet คุณจะต้องสร้างคลาสด้วยเมธอด run แบบไม่พร้อมกัน และ register คลาสนี้ให้เรียกใช้ใน iframe ของโฆษณา ภายใน sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

การแก้ไขข้อบกพร่อง

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

privateAggregation.enableDebugMode();

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

privateAggregation.enableDebugMode({debugKey: 1234});

การแก้ไขข้อบกพร่องของพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

พื้นที่เก็บข้อมูลที่ใช้ร่วมกันแสดงข้อความแสดงข้อผิดพลาดทั่วไปดังนี้

Promise is rejected without and explicit error message

คุณแก้ไขข้อบกพร่องของพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้โดยการรวมการเรียกใช้ด้วยการบล็อก try-catch

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

การแก้ไขข้อบกพร่องของการรวมส่วนตัว

รายงานจะส่งไปที่ /.well-known/private-aggregation/report-shared-storage และ /.well-known/private-aggregation/debug/report-shared-storage รายงานการแก้ไขข้อบกพร่องจะได้รับเพย์โหลดที่คล้ายกับ JSON ต่อไปนี้ เพย์โหลดนี้กำหนดช่อง api เป็น "พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน"

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

แก้ไขข้อบกพร่องเพย์โหลดข้อความที่โอนหรือจัดเก็บได้โดยไม่ต้องเข้ารหัส

debug_cleartext_payload มีการเข้ารหัส Base64 CBOR คุณจะดูที่เก็บข้อมูลและค่าได้โดยใช้เครื่องมือถอดรหัส หรือใช้โค้ด JavaScript ที่พบในตัวถอดรหัสพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

ขั้นตอนถัดไป

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

เมื่อคุ้นเคยกับ API แล้ว ก็เริ่มรวบรวมรายงานได้ ซึ่งจะส่งเป็นคำขอ POST ไปยังปลายทางต่อไปนี้ในรูปแบบ JSON ในเนื้อหาคำขอ

รายงานการแก้ไขข้อบกพร่อง - context-origin/.well-known/private-aggregation/debug/report-shared-storage
รายงาน - context-origin/.well-known/private-aggregation/report-shared-storage

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

แชร์ความคิดเห็น

คุณแชร์ความคิดเห็นเกี่ยวกับ API และเอกสารประกอบได้ใน GitHub