Các khái niệm chính của API tổng hợp riêng tư
Tài liệu này dành cho đối tượng nào?
API Tổng hợp riêng tư cho phép thu thập dữ liệu tổng hợp qua các Worklet có quyền truy cập vào dữ liệu trên nhiều trang web. Các khái niệm được chia sẻ ở đây rất quan trọng đối với việc nhà phát triển xây dựng báo cáo trong Bộ nhớ dùng chung và Protected Audience API.
- Nếu bạn là nhà phát triển đang xây dựng hệ thống báo cáo cho nhiều trang web đo lường.
- Nếu bạn là nhà tiếp thị, nhà khoa học dữ liệu hoặc báo cáo tóm tắt khác) người tiêu dùng, thì việc hiểu được các cơ chế này sẽ giúp bạn đưa ra quyết định để truy xuất báo cáo tóm tắt tối ưu hoá.
Từ khóa
Trước khi đọc tài liệu này, bạn nên tìm hiểu các thuật ngữ và khái niệm chính. Từng thuật ngữ trong số này sẽ được mô tả chi tiết tại đây.
- Khoá tổng hợp (còn gọi là bộ chứa) là một thu thập các điểm dữ liệu được xác định trước. Ví dụ: bạn nên thu thập một nhóm dữ liệu vị trí mà trình duyệt báo cáo quốc gia . Một khoá tổng hợp có thể chứa nhiều phương diện (ví dụ: quốc gia và mã nhận dạng của tiện ích nội dung).
- Giá trị tổng hợp là một điểm dữ liệu riêng lẻ
được thu thập thành một khoá tổng hợp. Nếu bạn muốn đo lường số lượng người dùng
từ Pháp đã xem nội dung của bạn, thì
Francelà một phương diện trong khoá tổng hợp vàviewCountcủa1là giá trị tổng hợp. - Báo cáo tổng hợp được tạo và mã hoá trong trình duyệt. Đối với API tổng hợp riêng tư, API này chứa dữ liệu về một sự kiện.
- Dịch vụ tổng hợp xử lý dữ liệu từ các báo cáo tổng hợp để tạo báo cáo tóm tắt.
- Báo cáo tóm tắt là kết quả cuối cùng của Dịch vụ tổng hợp, và chứa dữ liệu người dùng tổng hợp và dữ liệu lượt chuyển đổi chi tiết.
- worklet là một mảnh cho phép bạn chạy các hàm JavaScript cụ thể và trả lại thông tin cho người yêu cầu. Trong một worklet, bạn có thể thực thi JavaScript nhưng bạn không thể tương tác hoặc giao tiếp với trang bên ngoài.
Quy trình tổng hợp riêng tư
Khi bạn gọi API Tổng hợp riêng tư bằng một khoá tổng hợp và một giá trị tổng hợp thì trình duyệt sẽ tạo một báo cáo tổng hợp. Báo cáo được gửi đến máy chủ của bạn để phân lô các báo cáo. Các báo cáo theo lô là sau đó được Dịch vụ tổng hợp xử lý và tạo một báo cáo tóm tắt.
- Khi bạn gọi API Tổng hợp riêng tư, ứng dụng (trình duyệt) sẽ tạo rồi gửi báo cáo tổng hợp đến máy chủ của bạn để được thu thập.
- Máy chủ của bạn thu thập báo cáo từ máy khách và phân lô để gửi đến Dịch vụ tổng hợp.
- Khi đã thu thập đủ báo cáo, bạn sẽ phân theo lô và gửi chúng đến Dịch vụ tổng hợp, chạy trong một môi trường thực thi đáng tin cậy để tạo báo cáo tóm tắt.
Quy trình làm việc được mô tả trong phần này tương tự như quy trình Báo cáo phân bổ . Tuy nhiên, Attribution Báo cáo liên kết dữ liệu thu thập được từ một sự kiện hiển thị và một lượt chuyển đổi sự kiện xảy ra vào các thời điểm khác nhau. Tính năng Tổng hợp riêng tư đo lường một sự kiện trên nhiều trang web.
Khoá tổng hợp
Một khoá tổng hợp (gọi tắt là "khoá") đại diện cho nhóm chứa các giá trị tổng hợp sẽ được tích luỹ. Có thể mã hoá một hoặc nhiều phương diện vào khoá. Phương diện đại diện cho một số khía cạnh mà bạn muốn nhận được nhiều hơn thông tin chi tiết, chẳng hạn như nhóm tuổi người dùng hoặc số lần hiển thị của quảng cáo chiến dịch.
Ví dụ: có thể bạn có một tiện ích được nhúng trên nhiều trang web và muốn phân tích quốc gia của người dùng đã xem tiện ích của bạn. Bạn đang xem để trả lời các câu hỏi như "Có bao nhiêu người dùng đã nhìn thấy tiện ích của tôi từ Quốc gia X?" Để báo cáo về câu hỏi này, bạn có thể thiết lập khoá tổng hợp mã hoá hai thứ nguyên: mã tiện ích và mã quốc gia.
Khoá được cung cấp cho API Tổng hợp riêng tư là
BigInt,
bao gồm nhiều phương diện. Trong ví dụ này, phương diện là phương diện
ID tiện ích con và ID quốc gia. Giả sử mã tiện ích có thể có tối đa 4 chữ số
dài, chẳng hạn như 1234 và mỗi quốc gia được liên kết thành một số theo thứ tự bảng chữ cái
chẳng hạn như Afghanistan là 1, Pháp là 61 và Zimbabwe là "195".
Do đó, khoá tổng hợp sẽ có độ dài 7 chữ số, trong đó 4 chữ số đầu tiên
ký tự được dành riêng cho WidgetID và 3 ký tự cuối cùng là
dành riêng cho CountryID.
Giả sử khoá này thể hiện số lượng người dùng ở Pháp (mã quốc gia 061)
những người đã thấy mã tiện ích 3276, Khoá tổng hợp là 3276061.
| Khoá tổng hợp | |
| ID tiện ích | Mã quốc gia |
| 3276 | 061 |
Bạn cũng có thể tạo khoá tổng hợp bằng cơ chế băm, chẳng hạn như
SHA-256. Ví dụ: chuỗi
{"WidgetId":3276,"CountryID":67} có thể được băm, sau đó được chuyển đổi thành
Giá trị BigInt trong số
42943797454801331377966796057547478208888578253058197330928948081739249096287n.
Nếu giá trị hàm băm có nhiều hơn 128 bit, bạn có thể cắt bớt để đảm bảo giá trị đó không
vượt quá giá trị bộ chứa tối đa được phép là 2^128−1.
Trong một Worklet Bộ nhớ dùng chung, bạn có thể truy cập vào
crypto và
TextEncoder mô-đun
có thể giúp bạn tạo một hàm băm. Để tìm hiểu thêm về cách tạo hàm băm, hãy tham khảo
SubtleCrypto.digest() bật
Mã nhận dạng cho nhà quảng cáo (MDN).
Ví dụ sau đây mô tả cách bạn có thể tạo khoá bộ chứa từ một hàm băm giá trị:
async function convertToBucket(data) {
// Encode as UTF-8 Uint8Array
const encodedData = new TextEncoder().encode(data);
// Generate SHA-256 hash
const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);
// Truncate the hash
const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));
// Convert the byte sequence to a decimal
return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}
const data = {
WidgetId: 3276,
CountryID: 67
};
const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);
console.log(bucket); // 126200478277438733997751102134640640264n
Giá trị tổng hợp
Các giá trị tổng hợp được tổng hợp cho mỗi khoá qua nhiều người dùng để tạo ra các giá trị tổng hợp thông tin chi tiết dưới dạng giá trị tóm tắt trong báo cáo tóm tắt.
Bây giờ, hãy quay lại câu hỏi ví dụ được đưa ra trước đó: "Có bao nhiêu người dùng ai đã nhìn thấy tiện ích của tôi đến từ Pháp?" Câu trả lời cho câu hỏi này sẽ trông chẳng hạn như "Khoảng 4.881 người dùng đã xem ID tiện ích 3276 của tôi từ Pháp". Giá trị tổng hợp là 1 cho mỗi người dùng và "4881 người dùng" là giá trị tổng hợp là tổng tất cả giá trị tổng hợp cho mục đích đó khoá tổng hợp.
| Khoá tổng hợp | Giá trị tổng hợp | |
| ID tiện ích | Mã quốc gia | Số lượt xem |
| 3276 | 061 | 1 |
Trong ví dụ này, chúng ta tăng giá trị thêm 1 cho mỗi người dùng nhìn thấy tiện ích. Trong thực tế, bạn có thể điều chỉnh giá trị tổng hợp theo tỷ lệ để cải thiện tín hiệu so với nhiễu .
Ngân sách đóng góp
Mỗi lệnh gọi đến API Tổng hợp riêng tư được gọi là một khoản đóng góp. Để bảo vệ quyền riêng tư của người dùng, số lượng khoản đóng góp có thể thu thập được từ cá nhân bị hạn chế.
Khi bạn tính tổng tất cả giá trị tổng hợp trên tất cả các khoá tổng hợp, thì tổng phải thấp hơn ngân sách đóng góp. Ngân sách được đặt cho từng worklet origin, mỗi ngày và là tách biệt cho các Worklet Protected Audience API và Bộ nhớ dùng chung. Thúc đẩy khoảng thời gian 24 giờ qua sẽ được dùng cho ngày đó. Nếu một khách hàng mới báo cáo tổng hợp sẽ khiến ngân sách bị vượt quá, còn báo cáo thì không đã tạo.
Ngân sách đóng góp được biểu thị bằng thông số L1 và là được đặt thành 216 (65.536)/10 phút mỗi ngày với điểm dừng là 220
(1.048.576). Xem giải thích để tìm hiểu thêm về các thông số này.
Giá trị ngân sách đóng góp là tuỳ ý, nhưng độ nhiễu sẽ được điều chỉnh theo tỷ lệ. Bạn có thể sử dụng ngân sách này để tối đa hoá tỷ lệ tín hiệu so với độ nhiễu cho các giá trị tóm tắt (sẽ được thảo luận kỹ hơn trong phần Độ nhiễu và tỷ lệ).
Để tìm hiểu thêm về ngân sách khoản đóng góp, hãy xem giải thích. Ngoài ra, hãy tham khảo Đóng góp Ngân sách để xem thêm hướng dẫn.
Các báo cáo tổng hợp
Sau khi người dùng gọi API Tổng hợp riêng tư, trình duyệt sẽ tạo
các báo cáo tổng hợp để Dịch vụ tổng hợp xử lý sau này
kịp thời để tạo thông tin tóm tắt
báo cáo. Một
báo cáo tổng hợp có định dạng JSON và chứa một danh sách được mã hoá gồm
số lượt đóng góp, mỗi khoản là một cặp {aggregation key, aggregatable value}.
Các báo cáo tổng hợp được gửi với độ trễ ngẫu nhiên tối đa là một giờ.
Các nội dung đóng góp sẽ được mã hoá và không đọc được bên ngoài Dịch vụ tổng hợp. Dịch vụ tổng hợp giải mã báo cáo và tạo báo cáo tóm tắt. Chiến lược phát hành đĩa đơn khoá mã hoá dành cho trình duyệt và khoá giải mã dành cho công cụ Tổng hợp Dịch vụ do điều phối viên cung cấp, đóng vai trò là dịch vụ quản lý khoá. Điều phối viên lưu giữ một danh sách các hàm băm nhị phân của hình ảnh dịch vụ để xác minh phương thức gọi được phép nhận khoá giải mã.
Ví dụ về báo cáo tổng hợp có gỡ lỗi :
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
"payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
}
],
"debug_key": "777",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"
Bạn có thể kiểm tra các báo cáo tổng hợp từ
Trang chrome://private-aggregation-internals:
Đối với mục đích thử nghiệm, nút "Gửi các báo cáo đã chọn" Bạn có thể dùng nút này để gửi báo cáo cho máy chủ ngay lập tức.
Thu thập và phân lô các báo cáo tổng hợp
Trình duyệt gửi các báo cáo tổng hợp đến nguồn gốc của worklet chứa lệnh gọi đến API Tổng hợp riêng tư, sử dụng các hàm đường dẫn:
- Đối với bộ nhớ dùng chung:
/.well-known/private-aggregation/report-shared-storage - Đối với Protected Audience:
/.well-known/private-aggregation/report-protected-audience
Tại các điểm cuối này, bạn sẽ cần vận hành một máy chủ — đóng vai trò như một trình thu thập — nhận các báo cáo tổng hợp do khách hàng gửi.
Sau đó, máy chủ sẽ phải báo cáo theo lô và gửi lô đó đến mục Tổng hợp
Dịch vụ. Tạo các lô dựa trên thông tin có sẵn trong tệp chưa mã hoá
tải trọng của báo cáo tổng hợp, chẳng hạn như trường shared_info. Tốt nhất là bạn nên
các lô phải chứa 100 báo cáo trở lên trong mỗi lô.
Bạn có thể quyết định phân lô theo ngày hoặc tuần. Đây là chiến lược linh hoạt, và bạn có thể thay đổi chiến lược phân lô cho các sự kiện cụ thể mà bạn mong đợi khối lượng nhiều hơn—ví dụ: những ngày trong năm dự kiến sẽ có nhiều lượt hiển thị hơn. Lô phải bao gồm các báo cáo từ cùng một phiên bản API, nguồn gốc báo cáo và lập lịch thời gian báo cáo.
Dịch vụ tổng hợp
Dịch vụ tổng hợp nhận các báo cáo tổng hợp đã mã hoá từ trình thu thập và tạo bản tóm tắt .
Để giải mã tải trọng báo cáo, Dịch vụ tổng hợp tìm nạp khoá giải mã từ điều phối viên. Dịch vụ chạy trong một môi trường thực thi đáng tin cậy (TEE), mang lại mức độ đảm bảo về tính toàn vẹn của dữ liệu, tính bảo mật của dữ liệu và tính toàn vẹn của mã. Mặc dù bạn sở hữu và điều hành dịch vụ, bạn sẽ không có chế độ hiển thị dữ liệu đang được xử lý bên trong TEE.
Báo cáo tóm tắt
Báo cáo tóm tắt cho phép bạn xem dữ liệu đã thu thập cùng với dữ liệu nhiễu. Bạn có thể yêu cầu các báo cáo tóm tắt cho một tập hợp các khoá nhất định.
Báo cáo tóm tắt chứa một tập hợp các cặp khoá-giá trị kiểu từ điển JSON. Một cặp chứa:
bucket: khoá tổng hợp ở dạng chuỗi số nhị phân. Nếu khoá tổng hợp được dùng là "123", thì bộ chứa là "1111011".value: giá trị tóm tắt cho một mục tiêu đo lường nhất định, được tổng hợp từ tất cả báo cáo tổng hợp hiện có đã thêm dữ liệu gây nhiễu.
Ví dụ:
[
{"bucket":` `"111001001",` `"value":` `"2558500"},
{"bucket":` `"111101001",` `"value":` `"3256211"},
{"bucket":` `"111101001",` `"value":` `"6536542"},
]
Nhiễu và điều chỉnh tỷ lệ
Để bảo vệ quyền riêng tư của người dùng, Dịch vụ tổng hợp sẽ thêm nội dung gây nhiễu một lần cho mỗi mỗi khi yêu cầu báo cáo tóm tắt. Giá trị độ nhiễu là được vẽ ngẫu nhiên từ xác suất Laplace . Khi bạn không kiểm soát trực tiếp cách thêm nhiễu, bạn có thể tác động đến độ nhiễu trong dữ liệu đo lường.
Mức phân bổ độ nhiễu là như nhau bất kể tổng của tất cả tổng hợp là bao nhiêu giá trị. Do đó, giá trị tổng hợp càng cao thì độ nhiễu càng ít ảnh hưởng có thể có.
Ví dụ: giả sử hàm phân phối tạp âm có độ lệch chuẩn là 100 và có tâm ở 0. Nếu giá trị báo cáo tổng hợp đã thu thập (hoặc "giá trị tổng hợp") chỉ là 200, thì độ lệch chuẩn của nhiễu sẽ là 50% giá trị tổng hợp. Nhưng, nếu giá trị tổng hợp là 20.000, thì độ lệch chuẩn của nhiễu chỉ là 0,5% giá trị tổng hợp. Vì vậy, giá trị tổng hợp là 20.000 sẽ có tỷ lệ tín hiệu trên độ nhiễu cao hơn nhiều.
Do đó, việc nhân giá trị tổng hợp với một hệ số tỷ lệ có thể giúp giảm tiếng ồn. Hệ số tỷ lệ đại diện cho mức độ bạn muốn mở rộng một quy mô nhất định giá trị tổng hợp.
Tăng tỷ lệ giá trị bằng cách chọn hệ số tỷ lệ lớn hơn giúp giảm tỷ lệ tương đối tiếng ồn. Tuy nhiên, điều này cũng dẫn đến tổng tất cả các lượt đóng góp trên tất cả các nhóm để đạt hạn mức ngân sách đóng góp nhanh hơn. Giảm tỷ lệ các giá trị xuống việc chọn hằng số hệ số tỷ lệ nhỏ hơn sẽ làm tăng độ nhiễu tương đối, nhưng lại giảm nguy cơ đạt đến giới hạn ngân sách.
Để tính toán hệ số tỷ lệ phù hợp, hãy chia ngân sách đóng góp cho tổng tối đa của các giá trị tổng hợp trên tất cả các khoá.
Xem ngân sách đóng góp tài liệu để tìm hiểu thêm.
Thu hút và chia sẻ ý kiến phản hồi
API tổng hợp riêng tư đang trong quá trình thảo luận và có thể thay đổi trong tương lai. Nếu bạn dùng thử API này và có ý kiến phản hồi, chúng tôi rất mong nhận được ý kiến phản hồi của bạn.
- GitHub: Đọc giải thích, đặt câu hỏi và tham gia . * Hỗ trợ nhà phát triển: Đặt câu hỏi và tham gia thảo luận trên Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư kho lưu trữ. * Tham gia API Bộ nhớ dùng chung nhóm và Protected Audience API nhóm để biết các thông báo mới nhất liên quan đến tính năng Tổng hợp riêng tư.