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

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

หากมีการเข้าถึงพื้นที่เก็บข้อมูลที่ใช้ร่วมกันหลายครั้งในการโหลดหน้าเว็บเดียวกันด้วยคีย์เดียวกัน ระบบจะเขียนทับค่าของคีย์ คุณควรใช้ 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"

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

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

คุณตั้งค่าการล็อกได้โดยใช้ 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 : batchUpdate;methods="set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear"

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

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

await sharedStorage.get('mykey');

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

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

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

  • การใช้ JavaScript

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

    window.sharedStorage.delete('myKey');

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

    sharedStorage.delete('myKey');

    วิธีลบคีย์ทั้งหมดพร้อมกันจากภายนอกชิ้นงาน

    window.sharedStorage.clear();

    วิธีลบคีย์ทั้งหมดพร้อมกันจากในชิ้นงาน

    sharedStorage.clear();

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

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

    delete;key="myKey"

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

    clear;

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

คุณสามารถอ่านกลุ่มความสนใจของ Protected Audience ได้จากเวิร์กเลตพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน เมธอด 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);
}

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

ตัวเลือก

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

withLock

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

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

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

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

  • การใช้ JavaScript

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

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

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

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

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

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

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

อีกสถานการณ์หนึ่งที่การล็อกมีประโยชน์คือเมื่อมีคีย์หลายรายการที่ต้องอ่านร่วมกันในเวิร์กเลต และควรมีการซิงค์สถานะของคีย์เหล่านั้น ในกรณีนี้ คุณควรรวมการเรียกใช้ 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');
ตัวอย่างการแก้ไขคีย์หลายรายการ

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

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

// 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);

การเปลี่ยนบริบท

ระบบจะเขียนข้อมูลพื้นที่เก็บข้อมูลที่ใช้ร่วมกันลงในต้นทาง (เช่น 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' },
});

ในสคริปต์เวิร์กเลต คุณจะต้องสร้างคลาสที่มี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);

การใช้คำขอข้ามแหล่งที่มา

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