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

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

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

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

Shared Storage API

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

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

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

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

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

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

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

เช่นเดียวกับ 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() จากภายในหรือภายนอก Worklet JavaScript หากเรียกใช้จากภายนอกเวิร์กเลต ระบบจะเขียนข้อมูลไปยังต้นทางของบริบทการท่องเว็บที่เรียกใช้ หากเรียกใช้จากภายในเวิร์กเลต ระบบจะเขียนข้อมูลไปยังต้นทางของบริบทการท่องเว็บที่โหลดเวิร์กเลต คีย์ที่ตั้งไว้จะมีวันที่หมดอายุ 30 วันนับจากวันที่อัปเดตล่าสุด

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

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

การใช้ JavaScript

นอกชิ้นงาน

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'}

ในทํานองเดียวกัน ภายในชิ้นงาน

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 จากภายในหรือภายนอกเวิร์กเลต หรือใช้ส่วนหัวของคำตอบที่มี delete() หากต้องการลบแป้นทั้งหมดพร้อมกัน ให้ใช้ clear() จากแป้นพิมพ์ใดก็ได้

การใช้ JavaScript

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

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

Private Aggregation API

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

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

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

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

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

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

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

หากต้องการเปลี่ยนลักษณะการทํางานเริ่มต้น ให้ตั้งค่าพร็อพเพอร์ตี้ dataOrigin เมื่อเรียกใช้ createWorklet

dataOrigin: "context-origin": (ค่าเริ่มต้น) ระบบจะจัดเก็บข้อมูลไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันของต้นทางของบริบทการท่องเว็บที่เรียกใช้
dataOrigin: "script-origin": ระบบจะจัดเก็บข้อมูลไว้ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันของต้นทางสคริปต์เวิร์กเลต โปรดทราบว่าคุณต้องเลือกใช้เพื่อเปิดใช้โหมดนี้

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

หากต้องการเลือกใช้ เมื่อใช้ "script-origin" ปลายทางสคริปต์จะต้องตอบกลับด้วยส่วนหัว Shared-Storage-Cross-Origin-Worklet-Allowed โปรดทราบว่าคุณควรเปิดใช้ CORS สําหรับคําขอข้ามโดเมน

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

การใช้ iframe แบบข้ามต้นทาง

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

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

การใช้คำขอข้ามต้นทาง

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

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

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

ปลายทาง JavaScript แบบข้ามต้นทางจะต้องตอบกลับด้วยส่วนหัว Shared-Storage-Cross-Origin-Worklet-Allowed และโปรดทราบว่ามีการเปิดใช้ CORS สำหรับคำขอ

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

ชิ้นงานที่สร้างขึ้นโดยใช้ createWorklet() จะมี selectURL และ run() addModule() ไม่พร้อมใช้งานสำหรับการดำเนินการนี้

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

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

หน้าต่อไปนี้อธิบายแง่มุมที่สําคัญของ Shared Storage และ Private Aggregation API

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

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

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

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

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