Tài liệu này là hướng dẫn bắt đầu 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ị và tính năng Tổng hợp riêng tư tạo ra 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à các nhà cung cấp dịch vụ đo lường.
Dùng thử bản trình diễn
Dùng thử bản minh hoạ trực tiếp. Làm theo các bước trong hướng dẫn minh hoạ để bật các Privacy Sandbox API (API Hộp cát về quyền riêng tư). Việc mở Công cụ cho nhà phát triển của Chrome giúp bạn trực quan hoá kết quả của nhiều trường hợp sử dụng. Các trường hợp sử dụng có trong bản minh hoạ:
- Tổng hợp riêng tư
- Đo lường Phạm vi tiếp cận người dùng riêng biệt
- Đo lường thông tin nhân khẩu học
- Đo tần số K+
- Cách sử dụng chung
- Đo lường sự kiện di chuột qua bên trong khung được bảo vệ
- Thành phần điều hướng cấp cao
- Kiểm soát nơi bên thứ ba có thể ghi
Cách xem Bộ nhớ dùng chung
Để xem nội dung được lưu trữ trong Bộ nhớ dùng chung, hãy sử dụng Công cụ của Chrome cho nhà phát triển. Bạn có thể tìm thấy dữ liệu được lưu trữ trong Application -> Shared Storage.
Xem báo cáo cho tính năng Tổng hợp riêng tư
Để xem các báo cáo tổng hợp đã gửi, hãy chuyển đến chrome://private-aggregation-internals. Khi bạn bật chế độ gỡ lỗi, một báo cáo sẽ được gửi ngay lập tức (không bị trễ) đến [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage cùng với báo cáo bị trễ thời gian sẽ được gửi tới [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.
Để bật tính năng gỡ lỗi, hãy làm theo hướng dẫn trong phần gỡ lỗi.
API Bộ nhớ dùng chung
Để ngă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 mọi hình thức lưu trữ, bao gồm cả bộ nhớ cục bộ, cookie, v.v. Tuy nhiên, có những trường hợp sử dụng đòi hỏi phải có bộ nhớ không phân vùng. API Bộ nhớ dùng chung 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ị giới hạn ở 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 về dung lượng cho mỗi nguồn gốc, trong đó mỗi mục nhập được giới hạn ở một số ký tự tối đa. Nếu đạt đến giới hạn, thì 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 phần 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. Hoạt động đọc từ Bộ nhớ dùng chung chỉ diễn ra trong một môi trường JavaScript riêng biệt được gọi là worklet.
Sử dụng JavaScript. Công nghệ quảng cáo có thể thực hiện các chức năng cụ thể trong Bộ nhớ dùng chung, chẳng hạn như cài đặ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 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ể dùng bên ngoài trình làm việc JavaScript trong Khu vực API đề xuất – Bên ngoài worklet công việc.
Bạn có thể tìm thấy các phương thức được sử dụng trong worklet trong một thao tác tại phần Đề xuất API Surface – Trong worklet.
Sử dụng tiêu đề phản hồi
Tương tự như JavaScript, chỉ các chức năng cụ thể như cài đặt, thêm và xoá giá trị trong Bộ nhớ dùng chung mới có thể được thực hiện bằng tiêu đề phản hồi. Để xử lý được Bộ nhớ dùng chung trong tiêu đề phản hồi, bạn phải đưa
Shared-Storage-Writable: ?1vào tiêu đề của 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ẻ
iframehoặcimg<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>Sử dụng thuộc tính IDL với thẻ
iframehoặcimglet 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 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 công việc. Các khoá đã đặt có ngày hết hạn là 30 ngày kể từ lần cập nhật gần đây 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 hạn sử dụng 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 người dùng truy cập vào Bộ nhớ dùng chung nhiều lần trong cùng một lượt 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 tiêu đề phản hồi. Để thực hiện việc này, hãy sử dụng
Shared-Storage-Writetrong 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_presentShared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0Nhiều mục có thể được phân tách bằng dấu phẩy và có thể kết hợp
set,append,deletevàclear.Shared-Storage-Write : set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
Thêm một giá trị
Bạn có thể nối thêm giá trị vào khoá hiện có bằng phương thức nối. 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 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 thiết lập một giá trị trong Bộ nhớ dùng chung, bạn có thể sử dụng
Shared-Storage-Writetrong tiêu đề phản hồi để chuyể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 ngay trong một worklet.
await sharedStorage.get('mykey');
Nguồn gốc của ngữ cảnh duyệt web mà mô-đun worklet được tải từ đó xác định người mà Bộ nhớ dùng chung được đọc.
Đang xoá khỏi bộ nhớ dùng chung
Bạn có thể xoá khỏi Bộ nhớ dùng chung bằng cách dù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 sử dụng clear() trên 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 khỏi bên ngoài worklet:
window.sharedStorage.clear();Cách xoá tất cả cá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ể dùng
Shared-Storage-Writetrong tiêu đề phản hồi để truyền khoá cần xoá.delete;key="myKey"Cách xoá tất cả các khoá sử dụng tiêu đề phản hồi:
clear;
Chuyển đổi ngữ cảnh
Dữ liệu trong 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 mà cuộc gọi bắt nguồn.
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 iframe, mã sẽ nhận được ngữ cảnh duyệt web mới và 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 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 ngữ cảnh bên thứ nhất.
Bối cảnh 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 bối cảnh của 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 đó.
API tổng hợp riêng tư
Để đ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 một báo cáo, hãy gọi contributeToHistogram() bên trong một worklet với một bộ chứa và giá trị. Bộ chứa này đượ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ư, tải trọng của báo cáo (chứa bộ chứa và giá trị) sẽ được mã hoá trong quá trình chuyển dữ liệu. Bạn chỉ có thể giải mã và tổng hợp dữ liệu này bằng Dịch vụ tổng hợp.
Trình duyệt cũng sẽ giới hạn những nội dung mà một trang web có thể đóng góp cho truy vấn đầu ra. Cụ thể, ngân sách đóng góp giới hạn tổng mọi báo cáo trên một trang web 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, thì báo cáo sẽ không được tạo.
privateAggregation.contributeToHistogram({
bucket: BigInt(myBucket),
value: parseInt(myBucketValue)
});
Thực thi bộ nhớ dùng chung và tính năng tổng hợp riêng tư
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 công việc sharedStorageWorklet.js, trong cùng một iframe quảng cáo, hãy gọi sharedStorage.run().
await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
data: { campaignId: '1234' },
});
Trong tập lệnh worklet, bạn sẽ cần tạo một lớp bằng phương thức run không đồng bộ. Và register lớp này sẽ được 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: bucket,
value: value
});
}
}
register('shared-storage-report',
SharedStorageReportOperation);
Gỡ lỗi
Để bật tính năng gỡ lỗi, hãy gọi phương thức JavaScript enableDebugMode() trong cùng một ngữ cảnh khi sử dụng Bộ nhớ dùng chung và tính năng Tổng hợp riêng tư. Điều này sẽ được áp dụng cho các báo cáo sau này trong cùng ngữ cảnh.
privateAggregation.enableDebugMode();
Để liên kết báo cáo với những ngữ cảnh đã kích hoạt báo cáo, bạn có thể đặt khoá gỡ lỗi số nguyên 64 bit chưa ký. Khoá này được truyền đến lệnh gọi JavaScript. debugKey là một BigInt.
privateAggregation.enableDebugMode({debugKey: 1234});
Gỡ lỗi bộ nhớ dùng chung
Bộ nhớ dùng chung trả về thông báo lỗi chung:
Promise is rejected without and explicit error message
Bạn có thể gỡ lỗi Bộ nhớ dùng chung bằng cách gói các lệnh gọi với các khối try-catch.
try {
privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
console.log(e);
}
Gỡ lỗi tính năng Tổng hợp riêng tư
Báo cáo được gửi đến /.well-known/private-aggregation/report-shared-storage và /.well-known/private-aggregation/debug/report-shared-storage.
Báo cáo gỡ lỗi nhận tải trọng tương tự như JSON sau. Tải trọng này xác định trường api là "bộ nhớ dùng chung".
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [ {
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
"payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}
Gỡ lỗi tải trọng văn bản thô
debug_cleartext_payload được mã hoá Base64
CBOR. Bạn có thể xem nhóm và giá trị bằng cách sử dụng bộ giải mã hoặc sử dụng mã JavaScript có trong bộ giải mã Bộ nhớ dùng chung.
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 Bộ nhớ 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)
- 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)
- Tài liệu 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. Các báo cáo này sẽ được gửi dưới dạng yêu cầu POST đến các điểm cuối sau 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 thu thập báo cáo, bạn có thể kiểm thử bằng công cụ kiểm tra 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 của mình về các API và tài liệu trên GitHub.