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 nhanh về cách sử dụng Bộ nhớ dùng chung và tính năng Tổng hợp riêng tư. Bạn cần hiểu rõ về cả hai API vì Bộ nhớ dùng chung lưu trữ các giá trị, còn tính năng Tổng hợp riêng tư sẽ tạo các báo cáo tổng hợp.

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

Shared Storage API

Để ngăn chặn việc 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 bộ nhớ, bao gồm bộ nhớ cục bộ, cookie, v.v. Tuy nhiên, có một số trường hợp sử dụng yêu cầu bộ nhớ chưa 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ế ở nguồn gốc ngữ cảnh (phương thức gọi của sharedStorage).

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

Đang 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. Việc đọc từ Bộ nhớ dùng chung chỉ xảy ra trong một môi trường JavaScript riêng biệt được gọi là worklet.

Một worklet cho phép bạn chạy các hàm JavaScript cụ thể và trả về thông tin cho người yêu cầu. Trong một worklet, bạn có thể thực thi JavaScript nhưng không thể tương tác hoặc giao tiếp với trang bên ngoài.

Worklet dùng để lưu trữ và trích xuất dữ liệu bằng Shared Storage API (API Bộ nhớ dùng chung).

• 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, thêm và xoá các giá trị bên ngoài một công việc JavaScript. Tuy nhiên, các hàm như đọc Bộ nhớ dùng chung và thực hiện Tổng hợp riêng tư 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ể sử dụng bên ngoài worklet JavaScript trong phần Proposed API Surface – Outside the worklet (Giao diện API đề xuất – Bên ngoài worklet).

  Bạn có thể tìm thấy các phương thức được sử dụng trong worklet trong quá trình thao tác trong phần Proposed API Surface – In the worklet (Giao diện API đề xuất – 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 chức năng cụ thể như cài đặt, thêm và xoá giá trị trong Bộ nhớ dùng chung bằng cách sử dụng tiêu đề phản hồi. Để làm việc với Bộ nhớ dùng chung trong tiêu đề phản hồi, bạn phải đưa Shared-Storage-Writable: ?1 vào tiêu đề yêu cầu.

  Để bắt đầu một yêu cầu từ ứng dụng, hãy chạy 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ể xem thêm thông tin trong phần 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 là nơi thực hiện lệnh gọi. 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, thì 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 bạn truy cập vào Bộ nhớ dùng chung nhiều lần trong cùng một lần tải trang bằng cùng một khoá, thì giá trị của 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 các 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à có thể 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"
  

Nối một giá trị

Bạn có thể thêm giá trị vào khoá hiện có bằng phương thức bổ sung. Nếu khoá không tồn tại, lệnh 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 cách sử dụ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'}
  

  Cách 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 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 vào cặp khoá-giá trị.

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

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

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

await sharedStorage.get('mykey');

Nguồn gốc của ngữ cảnh duyệt web mà mô-đun worklet tải từ các xác định có đọc Bộ nhớ dùng chung.

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 cách sử dụng JavaScript từ bên trong hoặc bên ngoài worklet hoặc bằng cách sử dụng các tiêu đề phản hồi với delete(). Để xoá tất cả các khoá cùng một lúc, hãy sử dụng clear() từ một trong hai.

• 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ả khoá cùng một lúc từ bên ngoài worklet:

  window.sharedStorage.clear();
  

  Cách xoá tất cả khoá cùng một lúc từ bên 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ả khoá bằng tiêu đề phản hồi:

  clear;
  

Chuyển đổi ngữ cảnh

Dữ liệu của Bộ nhớ dùng chung được ghi vào nguồn gốc (ví dụ: https://example.adtech.com) của ngữ cảnh duyệt web là nguồn gốc của lệnh gọi.

Khi bạn tải mã của bên thứ ba bằng thẻ <script>, mã sẽ được thực thi trong ngữ 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 Bộ nhớ dùng chung của trình nhúng. Khi bạn tải mã của bên thứ ba trong một iframe, mã đó sẽ nhận được một ngữ 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.

Ngữ cảnh của bên thứ nhất

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

Ngữ cảnh của bên thứ ba

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

Private Aggregation API

Để đo lường dữ liệu tổng hợp được lưu trữ trong Bộ nhớ dùng chung, bạn có thể sử dụng API Tổng hợp riêng tư.

Để tạo báo cáo, hãy gọi contributeToHistogram() bên trong một worklet có một bộ chứa và giá trị. Bộ chứa được biểu thị bằng một số nguyên 128 bit chưa ký. Số nguyên này phải được truyền 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ư, trọng tải của báo cáo (chứa bộ chứa 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ố báo cáo của một trang web dành cho một trình duyệt cụ thể trong một khoảng thời gian nhất định trên tất cả các bộ chứa. Nếu vượt quá ngân sách hiện tại, báo cáo sẽ không được tạo.

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

Thực thi tính năng Bộ nhớ dùng chung và Tổng hợp riêng tư

Bạn phải tạo một worklet để truy cập dữ liệu từ bộ nhớ dùng chung. Để thực hiện việc này, hãy gọi createWorklet() bằng URL của công việc. 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, chứ không phải là 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 của ngữ cảnh duyệt web 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. Xin lưu ý rằng bạn phải chọn sử dụng thì mới có thể bật chế độ này.

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

Để chọn sử dụng, khi sử dụng "script-origin", điểm cuối của tập lệnh sẽ phải phản hồi bằng tiêu đề Shared-Storage-Cross-Origin-Worklet-Allowed. Xin lưu ý rằng bạn phải bật CORS cho các yêu cầu trên nhiều nguồn gốc.

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

Bạn có thể thiết lập `dataOrigin` trên `createWorklet()` và tạo các worklet đa nguồn gốc bằng `addModule()` trong M130.

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 đượ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 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. Bên trong 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à tính năng 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 lệnh gọi createWorklet() đến điểm cuối javascript nhiều nguồn gốc. Bạn cần đặt nguồn gốc phân vùng dữ liệu của worklet là 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

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

Lưu ý: Bạn có thể dùng addModule() để tạo các worklet trên nhiều nguồn gốc. Tuy nhiên, bạn nên sử dụng createWorklet() vì lớp này cho phép tạo phân vùng dữ liệu trên nhiều nguồn gốc và có thể tạo nhiều worklet, không giống như addModule().

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

Các bước tiếp theo

Các trang sau đây giải thích các khía cạnh quan trọng của API Lưu trữ dùng chung và API Tổng hợp riêng tư.

• Giới thiệu về Bộ nhớ dùng chung (Chrome dành cho nhà phát triển)
• Các trường hợp sử dụng bộ nhớ dùng chung (Chrome dành cho nhà phát triển)
• Giới thiệu về tính năng Tổng hợp riêng tư (Chrome dành cho nhà phát triển)
• Nội dung giải thích về Bộ nhớ dùng chung (GitHub)
• Giải thích về tính năng tổng hợp riêng tư (GitHub)
• Bản minh hoạ về Bộ nhớ dùng chung và tính năng tổng hợp riêng tư

Sau khi đã làm quen với các API, bạn có thể bắt đầu thu thập các báo cáo. Báo cáo này đượ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 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 báo cáo được thu thập, 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 Dịch vụ tổng hợp để 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 về các API và tài liệu trên GitHub.

• Bộ nhớ dùng chung
• Tổng hợp riêng tư