Bắt đầu nhanh việc triển khai bộ nhớ dùng chung và tính năng tổng hợp riêng tư

Tài liệu này là hướng dẫn bắt đầu nhanh để sử dụng Shared Storage và Private Aggregation. Bạn cần hiểu rõ cả hai API này vì Shared Storage lưu trữ các giá trị và Private Aggregation tạo ra các báo cáo có thể tổng hợp.

Đối tượng mục tiêu: Các nhà cung cấp công nghệ quảng cáo và giải pháp đo lường.

Shared Storage API

Để ngăn chặn hoạt động theo dõi trên nhiều trang web, các trình duyệt đã bắt đầu phân vùng tất cả các hình thức lưu trữ, bao gồm cả bộ nhớ cục bộ, cookie, v.v. Nhưng có những trường hợp sử dụng yêu cầu bộ nhớ không phân vùng. Shared Storage API cung cấp quyền ghi không giới hạn trên nhiều trang web cấp cao nhất với quyền đọc bảo đảm quyền riêng tư.

Bộ nhớ dùng chung bị hạn chế đối với nguồn gốc bối cảnh (người gọi sharedStorage).

Bộ nhớ dùng chung có hạn mức dung lượng cho mỗi nguồn gốc, trong đó mỗi mục nhập bị giới hạn ở số lượng ký tự tối đa. Nếu đạt đến hạn mức, hệ thống sẽ không lưu trữ thêm dữ liệu đầu vào nào. Hạn mức lưu trữ dữ liệu được nêu trong Giải thích về Shared Storage.

Gọi Bộ nhớ dùng chung

Công nghệ quảng cáo có thể ghi vào Bộ nhớ dùng chung bằng JavaScript hoặc tiêu đề phản hồi. Chỉ có thể đọc từ Bộ nhớ dùng chung trong một môi trường JavaScript riêng biệt gọi là worklet.

  • Sử dụng JavaScript Các công nghệ quảng cáo có thể thực hiện các chức năng cụ thể của Bộ nhớ dùng chung, chẳng hạn như đặt, nối và xoá các giá trị bên ngoài một worklet JavaScript. Tuy nhiên, các chức năng như đọc Shared Storage và thực hiện Private Aggregation phải được hoàn tất thông qua một worklet JavaScript. Bạn có thể tìm thấy các phương thức có thể dùng bên ngoài một worklet JavaScript trong Đề xuất giao diện API – Bên ngoài worklet.

    Bạn có thể tìm thấy các phương thức được dùng trong worklet trong quá trình hoạt động trong Đề xuất về giao diện API – Trong worklet.

  • Sử dụng tiêu đề phản hồi

    Tương tự như JavaScript, bạn chỉ có thể thực hiện các hàm cụ thể như đặt, nối và xoá giá trị trong Bộ nhớ dùng chung bằng cách sử dụng tiêu đề phản hồi. Để hoạt động với Bộ nhớ dùng chung trong tiêu đề phản hồi, Shared-Storage-Writable: ?1 phải có trong tiêu đề yêu cầu.

    Để bắt đầu một yêu cầu từ máy khách, hãy chạy đoạn mã sau, tuỳ thuộc vào phương thức bạn chọn:

    • Sử dụng fetch()

      fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});

    • Sử dụng thẻ iframe hoặc img

      <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>

    • Sử dụng thuộc tính IDL với thẻ iframe hoặc img

      let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";

Bạn có thể tìm thêm thông tin trong bài viết Bộ nhớ dùng chung: Tiêu đề phản hồi.

Ghi vào Bộ nhớ dùng chung

Để ghi vào Bộ nhớ dùng chung, hãy gọi sharedStorage.set() từ bên trong hoặc bên ngoài một worklet JavaScript. Nếu được gọi từ bên ngoài worklet, dữ liệu sẽ được ghi vào nguồn gốc của ngữ cảnh duyệt web mà lệnh gọi được thực hiện. Nếu được gọi từ bên trong worklet, dữ liệu sẽ được ghi vào nguồn gốc của ngữ cảnh duyệt web đã tải worklet. Các khoá được đặt có ngày hết hạn là 30 ngày kể từ lần cập nhật gần nhất.

Trường ignoreIfPresent là không bắt buộc. Nếu có và được đặt thành true, khoá sẽ không được cập nhật nếu đã tồn tại. Thời gian hết hạn của khoá được gia hạn thành 30 ngày kể từ lệnh gọi set() ngay cả khi khoá không được cập nhật.

Nếu Shared Storage được truy cập nhiều lần trong cùng một lần tải trang bằng cùng một khoá, thì giá trị cho khoá đó sẽ bị ghi đè. Bạn nên sử dụng sharedStorage.append() nếu khoá cần duy trì giá trị trước đó.

  • Sử dụng JavaScript

    Bên ngoài 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'}

    Tương tự, bên trong worklet:

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

  • Sử dụng tiêu đề phản hồi

    Bạn cũng có thể ghi vào Bộ nhớ dùng chung bằng tiêu đề phản hồi. Để thực hiện việc này, hãy sử dụng Shared-Storage-Write trong tiêu đề phản hồi cùng với các lệnh sau:

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

    Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0

    Bạn có thể phân tách nhiều mục bằng dấu phẩy và kết hợp set, append, delete và clear.

    Shared-Storage-Write :
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"

Thêm giá trị

Bạn có thể thêm một giá trị vào khoá hiện có bằng phương thức append. Nếu khoá không tồn tại, việc gọi append() sẽ tạo khoá và đặt giá trị. Bạn có thể thực hiện việc này bằng JavaScript hoặc tiêu đề phản hồi.

  • Sử dụng JavaScript

    Để cập nhật giá trị của các khoá hiện có, hãy sử dụng sharedStorage.append() từ bên trong hoặc bên ngoài 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'}

    Để nối bên trong worklet:

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

  • Sử dụng tiêu đề phản hồi

    Tương tự như việc đặt một giá trị trong Bộ nhớ dùng chung, bạn có thể sử dụng Shared-Storage-Write trong tiêu đề phản hồi để truyền cặp khoá-giá trị.

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

Cập nhật giá trị theo lô

Bạn có thể gọi sharedStorage.batchUpdate() từ bên trong hoặc bên ngoài một worklet JavaScript và truyền vào một mảng có thứ tự gồm các phương thức chỉ định các thao tác đã chọn. Mỗi hàm khởi tạo phương thức đều chấp nhận các tham số giống như phương thức riêng lẻ tương ứng cho các thao tác đặt, thêm, xoá và xoá.

Bạn có thể gọi batchUpdate() từ JavaScript hoặc sử dụng tiêu đề phản hồi:

  • Sử dụng JavaScript

    Sau đây là các phương thức JavaScript có thể dùng với batchUpdate():

    • SharedStorageSetMethod(): Ghi một cặp khoá-giá trị vào Shared Storage.
    • SharedStorageAppendMethod(): Nối một giá trị vào khoá hiện có trong Bộ nhớ dùng chung hoặc ghi một cặp khoá-giá trị nếu khoá chưa tồn tại.
    • SharedStorageDeleteMethod(): Xoá một cặp khoá-giá trị khỏi Bộ nhớ dùng chung.
    • SharedStorageClearMethod(): Xoá tất cả các khoá trong Bộ nhớ dùng chung.
    sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);

  • Sử dụng tiêu đề phản hồi

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

Việc sử dụng tiêu đề phản hồi sẽ thực hiện batchUpdate() cho tất cả các phương thức trong tiêu đề.

Đọc từ Bộ nhớ dùng chung

Bạn chỉ có thể đọc từ Bộ nhớ dùng chung trong một worklet.

await sharedStorage.get('mykey');

Nguồn gốc của bối cảnh duyệt web mà mô-đun worklet được tải sẽ xác định Shared Storage của ai được đọc.

Xoá khỏi Bộ nhớ dùng chung

Bạn có thể thực hiện thao tác xoá khỏi Bộ nhớ dùng chung bằng JavaScript từ bên trong hoặc bên ngoài worklet hoặc bằng cách sử dụng tiêu đề phản hồi với delete(). Để xoá tất cả các khoá cùng một lúc, hãy dùng clear() từ một trong hai khoá.

  • Sử dụng JavaScript

    Cách xoá khỏi Bộ nhớ dùng chung từ bên ngoài worklet:

    window.sharedStorage.delete('myKey');

    Cách xoá khỏi Bộ nhớ dùng chung từ bên trong worklet:

    sharedStorage.delete('myKey');

    Cách xoá tất cả các khoá cùng một lúc từ bên ngoài worklet:

    window.sharedStorage.clear();

    Cách xoá tất cả các khoá cùng một lúc trong worklet:

    sharedStorage.clear();

  • Sử dụng tiêu đề phản hồi

    Để xoá các giá trị bằng tiêu đề phản hồi, bạn cũng có thể sử dụng Shared-Storage-Write trong tiêu đề phản hồi để truyền khoá cần xoá.

    delete;key="myKey"

    Cách xoá tất cả các khoá bằng tiêu đề phản hồi:

    clear;

Đọc nhóm đối tượng có cùng mối quan tâm trong Protected Audience từ Bộ nhớ dùng chung

Bạn có thể đọc các nhóm có cùng mối quan tâm của Protected Audience từ một worklet Shared Storage. Phương thức interestGroups() trả về một mảng các đối tượng StorageInterestGroup, bao gồm các thuộc tính AuctionInterestGroup và GenerateBidInterestGroup.

Ví dụ sau đây cho thấy cách đọc các nhóm đối tượng có cùng mối quan tâm trong bối cảnh duyệt web và một số thao tác có thể thực hiện trên các nhóm đối tượng có cùng mối quan tâm đã truy xuất. Hai thao tác có thể được dùng là tìm số lượng nhóm mối quan tâm và tìm nhóm mối quan tâm có số lượng giá thầu cao nhất.

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

Nguồn gốc của bối cảnh duyệt web mà mô-đun worklet được tải từ đó sẽ xác định nguồn gốc của các nhóm lợi ích được đọc theo mặc định. Để tìm hiểu thêm về nguồn gốc mặc định của worklet và cách thay đổi nguồn gốc này, hãy xem phần Thực thi bộ nhớ dùng chung và Private Aggregation trong hướng dẫn về Shared Storage API.

Tùy chọn

Tất cả các phương thức đối tượng sửa đổi Shared Storage đều hỗ trợ một đối tượng tuỳ chọn không bắt buộc làm đối số cuối cùng.

withLock

Bạn không bắt buộc phải dùng lựa chọn withLock. Nếu được chỉ định, tuỳ chọn này sẽ hướng dẫn phương thức lấy khoá cho tài nguyên đã xác định bằng Web Locks API trước khi tiếp tục. Tên khoá được truyền khi yêu cầu khoá. Tên này đại diện cho một tài nguyên mà việc sử dụng được điều phối trên nhiều thẻ,worker hoặc mã trong nguồn gốc.

Bạn có thể sử dụng lựa chọn withLock với các phương thức đối tượng sửa đổi Shared Storage sau đây:

  • đặt
  • nối
  • xóa
  • xóa
  • cập nhật theo lô

Bạn có thể đặt khoá bằng cách sử dụng JavaScript hoặc tiêu đề phản hồi:

  • Sử dụng JavaScript

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

  • Sử dụng tiêu đề phản hồi

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

Các khoá Bộ nhớ dùng chung được phân vùng theo nguồn gốc dữ liệu. Các khoá này độc lập với mọi khoá thu được bằng phương thức LockManager, bất kể chúng có nằm trong ngữ cảnh window hay worker hay không. Tuy nhiên, chúng có cùng phạm vi với các khoá thu được bằng cách sử dụng request() trong ngữ cảnh SharedStorageWorklet.

Mặc dù phương thức request() cho phép nhiều lựa chọn cấu hình, nhưng các khoá thu được trong Bộ nhớ dùng chung luôn tuân thủ các chế độ cài đặt mặc định sau:

  • mode: "exclusive": Không thể giữ đồng thời các khoá khác có cùng tên.
  • steal: false: Các khoá hiện có có cùng tên sẽ không được phát hành để đáp ứng các yêu cầu khác.
  • ifAvailable: false: Các yêu cầu sẽ chờ vô thời hạn cho đến khi khoá có sẵn.
Trường hợp sử dụng withLock

Khoá rất hữu ích trong trường hợp có thể có nhiều worklet chạy đồng thời (ví dụ: nhiều worklet trên một trang hoặc nhiều worklet trong các thẻ khác nhau), mỗi worklet đều xem xét cùng một dữ liệu. Trong trường hợp đó, bạn nên bao bọc mã worklet có liên quan bằng một khoá để đảm bảo chỉ có một worklet xử lý báo cáo tại một thời điểm.

Một trường hợp khác mà khoá hữu ích là khi có nhiều khoá cần được đọc cùng nhau trong một worklet và trạng thái của chúng phải được đồng bộ hoá. Trong trường hợp đó, bạn nên bao bọc các lệnh gọi get bằng một khoá và đảm bảo có được cùng một khoá khi ghi vào các khoá đó.

Thứ tự khoá

Do bản chất của khoá web, các phương thức sửa đổi có thể không thực thi theo thứ tự mà bạn đã xác định. Nếu thao tác đầu tiên yêu cầu khoá và bị trì hoãn, thì thao tác thứ hai có thể bắt đầu trước khi thao tác đầu tiên kết thúc.

Ví dụ:

// 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');
Ví dụ về cách sửa đổi nhiều khoá

Lựa chọn withLock với batchUpdate() đảm bảo loại trừ lẫn nhau với các thao tác đồng thời khác đang lấy cùng một khoá. Bạn chỉ có thể áp dụng lựa chọn withLock cho batchUpdate() cho toàn bộ lô. Việc áp dụng withLock cho bất kỳ đối tượng phương thức riêng lẻ nào trong lô sẽ tạo ra một ngoại lệ.

Ví dụ này sử dụng một khoá để đảm bảo rằng các thao tác đọc và xoá trong worklet diễn ra cùng nhau, ngăn chặn sự can thiệp từ bên ngoài worklet.

Ví dụ modify-multiple-keys.js sau đây đặt các giá trị mới cho keyOne và keyTwo bằng modify-lock, sau đó thực thi thao tác modify-multiple-keys từ 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');

Sau đó, trong modify-multiple-keys-worklet.js, bạn có thể yêu cầu khoá bằng cách sử dụng navigator.locks.request() để đọc và sửa đổi các khoá nếu cần

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

Chuyển đổi ngữ cảnh

Dữ liệu Shared Storage được ghi vào nguồn gốc (ví dụ: https://example.adtech.com) của bối cảnh duyệt web mà lệnh gọi bắt nguồn từ đó.

Khi bạn tải mã của bên thứ ba bằng thẻ <script>, mã này sẽ được thực thi trong bối cảnh duyệt web của trình nhúng. Do đó, khi mã bên thứ ba gọi sharedStorage.set(), dữ liệu sẽ được ghi vào SharedStorage của trình nhúng. Khi bạn tải mã của bên thứ ba trong một iframe, mã này sẽ nhận được một bối cảnh duyệt web mới và nguồn gốc của mã là nguồn gốc của iframe. Do đó, lệnh gọi sharedStorage.set() được thực hiện từ iframe sẽ lưu trữ dữ liệu vào Bộ nhớ dùng chung của nguồn gốc iframe.

Bối cảnh của bên thứ nhất

Nếu một trang của bên thứ nhất đã nhúng mã JavaScript của bên thứ ba gọi sharedStorage.set() hoặc sharedStorage.delete(), thì cặp khoá-giá trị sẽ được lưu trữ trong bối cảnh của bên thứ nhất.

Dữ liệu được lưu trữ trong trang của bên thứ nhất có JavaScript được nhúng của bên thứ ba.
Sơ đồ mô tả dữ liệu được lưu trữ trong trang của bên thứ nhất có JavaScript được nhúng của bên thứ ba.

Bối cảnh của bên thứ ba

Cặp khoá-giá trị có thể được lưu trữ trong bối cảnh công nghệ quảng cáo hoặc bên thứ ba bằng cách tạo một iframe và gọi set() hoặc delete() trong mã JavaScript từ bên trong iframe.

Dữ liệu được lưu trữ trong bối cảnh công nghệ quảng cáo hoặc bối cảnh bên thứ ba.
Sơ đồ mô tả dữ liệu được lưu trữ trong bối cảnh công nghệ quảng cáo hoặc bên thứ ba.

Private Aggregation API

Để đo lường dữ liệu có thể tổng hợp được lưu trữ trong Shared Storage, bạn có thể sử dụng Private Aggregation API.

Để tạo báo cáo, hãy gọi contributeToHistogram() bên trong một worklet có một nhóm và giá trị. Nhóm được biểu thị bằng một số nguyên không dấu 128 bit. Bạn phải truyền số nguyên này vào hàm dưới dạng BigInt. Giá trị là một số nguyên dương.

Để bảo vệ quyền riêng tư, tải trọng của báo cáo (chứa nhóm và giá trị) sẽ được mã hoá trong quá trình truyền và chỉ có thể được giải mã và tổng hợp bằng Dịch vụ tổng hợp.

Trình duyệt cũng sẽ giới hạn những đóng góp mà một trang web có thể thực hiện cho một truy vấn đầu ra. Cụ thể, ngân sách đóng góp giới hạn tổng số tất cả các báo cáo từ một trang web duy nhất cho một trình duyệt nhất định trong một khoảng thời gian nhất định trên tất cả các nhóm. Nếu vượt quá ngân sách hiện tại, thì báo cáo sẽ không được tạo.

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

Thực thi Shared Storage và Private Aggregation

Theo mặc định, khi sử dụng bộ nhớ dùng chung với createWorklet(), nguồn gốc phân vùng dữ liệu sẽ là nguồn gốc của ngữ cảnh duyệt web đang gọi, chứ không phải nguồn gốc của chính tập lệnh worklet.

Để thay đổi hành vi mặc định, hãy đặt thuộc tính dataOrigin khi gọi createWorklet.

  • dataOrigin: "context-origin": (Mặc định) Dữ liệu được lưu trữ trong bộ nhớ dùng chung của nguồn gốc ngữ cảnh duyệt web đang gọi.
  • dataOrigin: "script-origin": Dữ liệu được lưu trữ trong bộ nhớ dùng chung của nguồn gốc tập lệnh worklet. Bạn phải chọn sử dụng để bật chế độ này.
  • dataOrigin: "https://custom-data-origin.example": Dữ liệu được lưu trữ trong bộ nhớ dùng chung của một nguồn dữ liệu tuỳ chỉnh. Bạn phải chọn sử dụng chế độ này và có được sự đồng ý của chủ sở hữu nguồn dữ liệu tuỳ chỉnh, như được nêu chi tiết trong phần Nguồn dữ liệu tuỳ chỉnh.
sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Để chọn sử dụng, khi dùng "script-origin" hoặc một nguồn gốc tuỳ chỉnh, điểm cuối tập lệnh phải phản hồi bằng tiêu đề Shared-Storage-Cross-Origin-Worklet-Allowed. Đối với các yêu cầu trên nhiều nguồn gốc, bạn cũng nên bật CORS.

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

Bạn cũng có thể chạy các tập lệnh trên nhiều nguồn gốc bằng cách sử dụng iframe của bên thứ ba. Trong trường hợp này, các thao tác Shared Storage sẽ nằm trong bối cảnh duyệt web của bên thứ ba.

Sử dụng iframe trên nhiều nguồn gốc

Bạn cần có iframe để gọi worklet bộ nhớ dùng chung.

Trong iframe của quảng cáo, hãy tải mô-đun worklet bằng cách gọi addModule(). Để chạy phương thức đã đăng ký trong tệp worklet sharedStorageWorklet.js, trong cùng một JavaScript iframe quảng cáo, hãy gọi sharedStorage.run().

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Trong tập lệnh worklet, bạn sẽ cần tạo một lớp có phương thức run không đồng bộ và register để chạy trong iframe của quảng cáo. Trong nhà sharedStorageWorklet.js:

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

Sử dụng yêu cầu trên nhiều nguồn gốc

Bộ nhớ dùng chung và Phép tổng hợp riêng tư cho phép tạo các worklet trên nhiều nguồn gốc mà không cần iframe trên nhiều nguồn gốc.

Trang của bên thứ nhất cũng có thể gọi createWorklet() đến điểm cuối JavaScript trên nhiều nguồn. Bạn sẽ cần đặt nguồn gốc phân vùng dữ liệu của worklet thành nguồn gốc của tập lệnh khi tạo 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();

Điểm cuối javascript nhiều nguồn gốc sẽ phải phản hồi bằng các tiêu đề Shared-Storage-Cross-Origin-Worklet-Allowed và lưu ý rằng CORS được bật cho yêu cầu.

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

Worklet được tạo bằng createWorklet() sẽ có selectURL và run(). addModule() không dùng được cho việc này.

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

Nguồn dữ liệu tuỳ chỉnh

Khi dataOrigin được đặt thành một nguồn gốc hợp lệ, chủ sở hữu của dataOrigin phải đồng ý với việc xử lý Bộ nhớ dùng chung cho dataOrigin đó bằng cách lưu trữ một tệp JSON liệt kê nguồn gốc của tập lệnh worklet tại đường dẫn /.well-known/shared-storage/trusted-origins. Tệp này phải là một mảng các đối tượng có khoá scriptOrigin và contextOrigin. Giá trị của các khoá này có thể là một chuỗi hoặc một mảng chuỗi.

Tạo tệp trusted-origins bằng thông tin sau:

  • Bối cảnh của người gọi
  • Nguồn gốc và URL của tập lệnh worklet
  • Nguồn gốc và chủ sở hữu dữ liệu

Bảng sau đây cho thấy cách bạn có thể tạo tệp trusted-origins dựa trên thông tin này:

Bối cảnh của người gọi URL tập lệnh worklet Nguồn gốc dữ liệu Chủ sở hữu dữ liệu Tệp JSON trusted-origins của chủ sở hữu nguồn gốc dữ liệu
https://publisher.example https://publisher.example/script.js context-origin https://publisher.example Không cần JSON
https://publisher.example https://ad.example/script.js script-origin https://ad.example Không cần JSON
https://publisher.example https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
Người gọi bất kỳ https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
https://publisher-a.example, HOẶC https://publisher-b.example https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
https://publisher.example https://cdn-a-ad.example/script.js, HOẶC https://cdn-b-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": [
    "https://cdn-a-ad.example",
    "https://cdn-b-ad.example"
  ],
  "contextOrigin": "https://publisher.example"
}]

Ví dụ: JSON sau đây có thể được lưu trữ tại https://custom-data-origin.example/.well-known/shared-storage/trusted-origins và kết hợp tất cả các bộ xử lý được phép của dữ liệu Bộ nhớ dùng chung cho nguồn gốc 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"
    ]
}]

Các bước tiếp theo

Các trang sau đây giải thích những khía cạnh quan trọng của Shared Storage API và Private Aggregation API.

Sau khi làm quen với các API này, bạn có thể bắt đầu thu thập báo cáo. Báo cáo được gửi dưới dạng yêu cầu POST đến các điểm cuối sau đây dưới dạng JSON trong phần nội dung yêu cầu.

  • Báo cáo gỡ lỗi – context-origin/.well-known/private-aggregation/debug/report-shared-storage
  • Báo cáo – context-origin/.well-known/private-aggregation/report-shared-storage

Sau khi thu thập báo cáo, bạn có thể kiểm thử bằng công cụ kiểm thử cục bộ hoặc thiết lập Môi trường thực thi đáng tin cậy cho Aggregation Service để nhận báo cáo tổng hợp.

Chia sẻ ý kiến phản hồi của bạn

Bạn có thể chia sẻ ý kiến phản hồi của mình về các API và tài liệu trên GitHub.