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

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

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

Shared Storage API

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

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

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

การเรียกใช้ Shared Storage

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

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

  คุณดูเมธอดที่ใช้ใน Worklet ระหว่างการดำเนินการได้ใน Proposed API Surface - In the worklet

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

  เช่นเดียวกับ 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";
    

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

การเขียนไปยัง Shared Storage

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

  ในทำนองเดียวกัน ภายใน 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() จากภายในหรือภายนอก Worklet

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

  วิธีต่อท้ายภายใน Worklet

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

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

  คุณใช้ Shared-Storage-Write ในส่วนหัวของการตอบกลับเพื่อส่งคู่คีย์-ค่าได้เช่นเดียวกับการตั้งค่าในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

การอัปเดตค่าแบบเป็นกลุ่ม

คุณสามารถเรียกใช้ sharedStorage.batchUpdate() จากภายในหรือภายนอก Worklet ของ JavaScript และส่งอาร์เรย์ของเมธอดที่เรียงลำดับซึ่งระบุการดำเนินการที่เลือก ตัวสร้างแต่ละวิธีจะยอมรับพารามิเตอร์เดียวกันกับวิธีแต่ละวิธีที่เกี่ยวข้องสำหรับ set, append, delete และ clear

คุณเรียกใช้ batchUpdate() จาก JavaScript หรือใช้ส่วนหัวการตอบกลับได้โดยทำดังนี้

• การใช้ JavaScript

  เมธอด JavaScript ที่ใช้กับ batchUpdate() ได้มีดังนี้

  • SharedStorageSetMethod(): เขียนคู่คีย์-ค่าไปยังพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
  • SharedStorageAppendMethod(): เพิ่มค่าลงในคีย์ที่มีอยู่ในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน หรือเขียนคู่คีย์-ค่าหากยังไม่มีคีย์
  • SharedStorageDeleteMethod(): ลบคู่คีย์-ค่าจากพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน
  • SharedStorageClearMethod(): ล้างคีย์ทั้งหมดในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

  sharedStorage.batchUpdate([
  new SharedStorageSetMethod('keyOne', 'valueOne'),
  new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
  new SharedStorageDeleteMethod('keyThree'),
  new SharedStorageClearMethod()
  ]);
  

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

  Shared-Storage-Write : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear
  

การใช้ส่วนหัวการตอบกลับจะดำเนินการ batchUpdate() สำหรับทุกเมธอดในส่วนหัว

การอ่านจาก Shared Storage

คุณจะอ่านจาก Shared Storage ได้จากภายใน Worklet เท่านั้น

await sharedStorage.get('mykey');

ต้นทางของบริบทการท่องเว็บที่โหลดโมดูล Worklet จะเป็นตัวกำหนดว่าระบบจะอ่าน Shared Storage ของใคร

การลบออกจาก Shared Storage

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

• การใช้ JavaScript

  วิธีลบออกจาก Shared Storage จากภายนอก Worklet

  window.sharedStorage.delete('myKey');
  

  วิธีลบออกจาก Shared Storage จากภายใน Worklet

  sharedStorage.delete('myKey');
  

  หากต้องการลบคีย์ทั้งหมดพร้อมกันจากภายนอก Worklet ให้ทำดังนี้

  window.sharedStorage.clear();
  

  หากต้องการลบคีย์ทั้งหมดพร้อมกันจากภายใน Worklet ให้ทำดังนี้

  sharedStorage.clear();
  

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

  หากต้องการลบค่าโดยใช้ส่วนหัวของการตอบกลับ คุณยังใช้ Shared-Storage-Write ในส่วนหัวของการตอบกลับเพื่อส่งคีย์ที่จะลบได้ด้วย

  delete;key="myKey"
  

  วิธีลบคีย์ทั้งหมดโดยใช้ส่วนหัวของการตอบกลับ

  clear;
  

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

คุณอ่านกลุ่มความสนใจของ Protected Audience จาก Worklet ของพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้ เมธอด interestGroups() จะแสดงผลอาร์เรย์ของออบเจ็กต์ StorageInterestGroup ซึ่งรวมถึงแอตทริบิวต์ AuctionInterestGroup และ GenerateBidInterestGroup

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

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

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

ตัวเลือก

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

withLock

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

withLock สามารถใช้กับวิธีการแก้ไขพื้นที่เก็บข้อมูลที่ใช้ร่วมกันต่อไปนี้

• ตั้งค่า
• ต่อท้าย
• ลบ
• ล้าง
• การอัปเดตเป็นกลุ่ม

คุณตั้งค่าการล็อกได้โดยใช้ JavaScript หรือส่วนหัวการตอบกลับ ดังนี้

• การใช้ JavaScript

  sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
  

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

  Shared-Storage-Write : set;key="myKey";value="myValue",options;with_lock="myResource"
  

การล็อกพื้นที่เก็บข้อมูลที่แชร์จะแบ่งพาร์ติชันตามแหล่งที่มาของข้อมูล โดยการล็อกจะไม่ขึ้นอยู่กับการล็อกที่ได้จากเมธอด LockManager request() ไม่ว่าการล็อกจะอยู่ในบริบท window หรือ worker ก็ตาม อย่างไรก็ตาม ทั้งสองจะใช้ขอบเขตเดียวกันกับล็อกที่ได้รับโดยใช้ request() ภายในบริบท SharedStorageWorklet

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

• mode: "exclusive": คุณจะถือล็อกอื่นที่มีชื่อเดียวกันพร้อมกันไม่ได้
• steal: false: ระบบจะไม่ปล่อยล็อกที่มีอยู่ซึ่งมีชื่อเดียวกันเพื่อรองรับคำขออื่นๆ
• ifAvailable: false: คำขอจะรอไปเรื่อยๆ จนกว่าจะมีการล็อก

กรณีที่ควรใช้ withLock

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

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

ลำดับการล็อก

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

ตัวอย่างเช่น:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

ตัวอย่างการแก้ไขคีย์หลายรายการ

ตัวเลือก withLock ที่มี batchUpdate() จะช่วยให้มั่นใจได้ว่าการดำเนินการพร้อมกันอื่นๆ ที่ได้ล็อกเดียวกันจะไม่รวมกัน คุณใช้ตัวเลือก withLock สำหรับ batchUpdate() กับทั้งชุดได้เท่านั้น การใช้ withLock กับออบเจ็กต์เมธอดแต่ละรายการภายในกลุ่มจะทำให้เกิดข้อยกเว้น

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

modify-multiple-keys.js ตัวอย่างต่อไปนี้จะตั้งค่าใหม่สำหรับ keyOne และ keyTwo ด้วย modify-lock จากนั้นจะดำเนินการ modify-multiple-keys จาก Worklet

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

จากนั้นภายใน modify-multiple-keys-worklet.js คุณสามารถขอการล็อกโดยใช้ navigator.locks.request() เพื่ออ่านและแก้ไขคีย์ได้ตามต้องการ

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

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

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

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

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

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

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

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

Private Aggregation API

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

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

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

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

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

การดำเนินการ Shared Storage และการรวมข้อมูลแบบส่วนตัว

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

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

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

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

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

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin: *

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

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

ต้องมี iframe เพื่อเรียกใช้ Worklet ของ Shared Storage

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

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 แบบข้ามต้นทางได้ด้วย คุณจะต้องตั้งค่าต้นทางของพาร์ติชันข้อมูล ของ Worklet ให้เป็นต้นทางของสคริปต์เมื่อสร้าง Worklet

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

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

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

แหล่งข้อมูลที่กำหนดเอง

เมื่อตั้งค่า dataOrigin เป็นต้นทางที่ถูกต้อง เจ้าของ dataOrigin ต้องยินยอมให้ประมวลผลพื้นที่เก็บข้อมูลที่ใช้ร่วมกันสำหรับ dataOrigin นั้นโดยการโฮสต์ไฟล์ JSON ที่แสดงรายการต้นทางของสคริปต์ Worklet ที่เส้นทาง /.well-known/shared-storage/trusted-origins ไฟล์ควรเป็นอาร์เรย์ของออบเจ็กต์ที่มีคีย์ scriptOrigin และ contextOrigin ค่าของคีย์เหล่านี้อาจเป็นสตริงหรืออาร์เรย์ของสตริงก็ได้

สร้างไฟล์ trusted-origins โดยใช้ข้อมูลต่อไปนี้

• บริบทของผู้โทร
• ต้นทางและ URL ของสคริปต์ Worklet
• แหล่งที่มาและเจ้าของข้อมูล

ตารางต่อไปนี้แสดงวิธีสร้างไฟล์ trusted-origins ตามข้อมูลนี้

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
      

[{
  "scriptOrigin": [
    "https://cdn-a-ad.example",
    "https://cdn-b-ad.example"
  ],
  "contextOrigin": "https://publisher.example"
}]
      

เช่น JSON ต่อไปนี้สามารถโฮสต์ที่ https://custom-data-origin.example/.well-known/shared-storage/trusted-origins และรวมโปรเซสเซอร์ที่ได้รับอนุญาตทั้งหมดของข้อมูลพื้นที่เก็บข้อมูลที่ใช้ร่วมกันสำหรับต้นทาง https://custom-data-origin.example

[
  {
    "scriptOrigin": "https://script-origin.a.example",
    "contextOrigin": "https://context-origin.a.example"
  },
  {
    "scriptOrigin": "https://script-origin.b.example",
    "contextOrigin": [
      "https://context-origin.a.example",
      "https://context-origin.b.example"
    ]
}]

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

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

• ข้อมูลเบื้องต้นเกี่ยวกับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน (Chrome สำหรับนักพัฒนาซอฟต์แวร์)
• กรณีการใช้งานพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน (Chrome สำหรับนักพัฒนาซอฟต์แวร์)
• ข้อมูลเบื้องต้นเกี่ยวกับการรวบรวมข้อมูลแบบส่วนตัว (Chrome สำหรับนักพัฒนาซอฟต์แวร์)
• คำอธิบายเกี่ยวกับพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน (GitHub)
• คำอธิบายการรวบรวมข้อมูลแบบส่วนตัว (GitHub)
• การสาธิตพื้นที่เก็บข้อมูลที่ใช้ร่วมกันและการรวมข้อมูลส่วนตัว

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

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

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

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

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

• Shared Storage
• การรวมข้อมูลแบบส่วนตัว