Kiến thức cơ bản về API tổng hợp riêng tư

Các khái niệm chính về 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 từ các công việc 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 đóng vai trò quan trọng đối với các nhà phát triển xây dựng chức nă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 để đo lường trên nhiều trang web.
• Nếu bạn là nhà tiếp thị, nhà khoa học dữ liệu hoặc người tiêu dùng báo cáo tóm tắt khác, việc hiểu rõ các cơ chế này sẽ giúp bạn đưa ra quyết định thiết kế để truy xuất báo cáo tóm tắt được tối ưu hoá.

Từ khóa

Trước khi đọc tài liệu này, bạn có thể tìm hiểu các thuật ngữ và khái niệm chính. Từng điều khoản 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 tập hợp các điểm dữ liệu được xác định trước. Ví dụ: bạn có thể cần thu thập một nhóm dữ liệu vị trí nơi trình duyệt báo cáo tên 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 cho tiện ích nội dung của bạn).
• Giá trị tổng hợp là một điểm dữ liệu riêng lẻ được thu thập vào khoá tổng hợp. Nếu bạn muốn đo lường số lượng người dùng ở Pháp đã xem nội dung của bạn, thì France là một phương diện trong khoá tổng hợp và viewCount của 1 là 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ư, tệp 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 tổng hợp gây nhiễu của người dùng và dữ liệu chuyển đổi chi tiết.
• worklet là một phần cơ sở hạ tầng cho phép bạn chạy các hàm JavaScript cụ thể và trả về thông tin cho trình 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.

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, 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ô báo cáo. Dịch vụ tổng hợp sẽ xử lý các báo cáo theo lô sau đó và một báo cáo tóm tắt sẽ được tạo.

1. Khi bạn gọi API tổng hợp riêng tư, máy khách (trình duyệt) sẽ tạo và gửi báo cáo tổng hợp đến máy chủ của bạn để được thu thập.
2. Máy chủ của bạn thu thập các báo cáo từ các ứng dụng và phân lô chúng để gửi đến Dịch vụ tổng hợp.
3. Sau khi thu thập đủ báo cáo, bạn sẽ phân lô và gửi các báo cáo đó đến Dịch vụ tổng hợp (chạy trong môi trường thực thi đáng tin cậy) để tạo báo cáo tóm tắt.

Từ khoá quan trọng: Môi trường thực thi đáng tin cậy là một cấu hình đặc biệt của phần cứng và phần mềm máy tính cho phép các bên bên ngoài xác minh phiên bản chính xác của phần mềm đang chạy trên máy tính. TEE cho phép bên ngoài xác minh rằng phần mềm hoạt động chính xác theo đúng những gì nhà sản xuất phần mềm tuyên bố, bất kể nhiều hay ít.

Quy trình công việc được mô tả trong phần này tương tự như Attribution Reporting API. Tuy nhiên, Báo cáo phân bổ liên kết dữ liệu đã thu thập được từ một sự kiện hiển thị và một sự kiện chuyển đổi xảy ra ở 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 duy nhất trên nhiều trang web.

Khoá tổng hợp

Khoá tổng hợp ("gọi tắt là "key") đại diện cho nhóm chứa các giá trị tổng hợp sẽ được tích luỹ. Bạn có thể mã hoá một hoặc nhiều kích thước vào khoá. Phương diện đại diện cho khía cạnh nào đó mà bạn muốn có thông tin chi tiết hơn, chẳng hạn như nhóm tuổi của người dùng hoặc số lượt hiển thị của một chiến dịch quảng cáo.

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 những người dùng đã nhìn thấy tiện ích của bạn. Bạn đang muốn trả lời các câu hỏi như "Có bao nhiêu người dùng đã xem tiện ích của tôi đến từ Quốc gia X?" Để báo cáo về câu hỏi này, bạn có thể thiết lập một khoá tổng hợp mã hoá hai chiều: 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, các phương diện là mã tiện ích và mã quốc gia. Giả sử mã tiện ích có thể dài tối đa 4 chữ số, 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ó 7 chữ số, trong đó 4 ký tự đầu tiên dành riêng cho WidgetID và 3 ký tự cuối cùng được dành riêng cho CountryID.

Giả sử khoá này biểu thị số lượng người dùng ở Pháp (Mã quốc gia 061) đã thấy mã tiện ích 3276, thì Khoá tổng hợp là 3276061.

Khoá tổng hợp
Mã tiện ích	Mã quốc gia
3276	061

Ví dụ: Nếu một phương diện có không gian khoá cho nhiều chữ số, nhưng giá trị có ít hơn, hãy thêm số 0 ở đầu. Ví dụ: Nếu mã quốc gia cho phép có 3 chữ số, thì mã quốc gia của Algeria là 003.

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 đó chuyển đổi thành giá trị BigInt của 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Nếu giá trị băm có nhiều hơn 128 bit, bạn có thể cắt ngắn để đảm bảo giá trị đó không vượt quá giá trị nhóm tối đa được phép là 2^128−1.

Trong worklet Bộ nhớ dùng chung, bạn có thể truy cập vào các mô-đun crypto và TextEncoder có thể giúp bạn tạo hàm băm. Để tìm hiểu thêm về cách tạo hàm băm, hãy xem nội dung SubtleCrypto.digest() trên MN.

Ví dụ sau đây mô tả cách bạn có thể tạo khoá bộ chứa từ một giá trị đã băm:

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

Lưu ý: Mặc dù các khái niệm tương tự nhau, nhưng khoá được tạo cho API Tổng hợp riêng tư sẽ khác với API Báo cáo phân bổ. Đối với tính năng Tổng hợp riêng tư, khoá hoàn chỉnh được chỉ định một lần, trong lệnh gọi JavaScript.

Giá trị tổng hợp

Các giá trị tổng hợp được tổng hợp theo từng khoá đối với nhiều người dùng để tạo thông tin chi tiết tổng hợp 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 mẫu đã đặt ra trước đó: "Có bao nhiêu người dùng đã 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ẽ có dạng như "Khoảng 4881 người dùng đã thấy ID tiện ích 3276 của tôi đến 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 của tất cả giá trị tổng hợp của khoá tổng hợp đó.

Khoá tổng hợp		Giá trị tổng hợp
Mã tiện ích	Mã quốc gia	Số lượt xem
3276	061	1

Trong ví dụ này, chúng tôi tăng giá trị thêm 1 cho mỗi người dùng nhìn thấy tiện ích đó. Trên thực tế, bạn có thể điều chỉnh tỷ lệ giá trị tổng hợp để cải thiện tỷ lệ tín hiệu trên độ 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 đóng góp. Để bảo vệ quyền riêng tư của người dùng, chúng tôi giới hạn số lượng nội dung đóng góp mà một cá nhân có thể đóng góp.

Khi bạn tính tổng tất cả giá trị tổng hợp trên tất cả khoá tổng hợp, tổng số đó phải nhỏ hơn ngân sách đóng góp. Ngân sách này được đặt trong phạm vi nguồn gốc cho mỗi công việc, theo ngày và được tách biệt với các công việc liên quan đến Protected Audience API và Bộ nhớ dùng chung. Hệ thống sẽ sử dụng một khung thời gian luân phiên khoảng 24 giờ qua cho ngày đó. Nếu một báo cáo tổng hợp mới khiến ngân sách vượt quá, thì báo cáo sẽ không được tạo.

Ngân sách đóng góp được biểu thị bằng thông số L₁ và được đặt thành 2¹⁶ (65.536)/10 phút/ngày với điểm dừng là 2²⁰

(1.048.576). Hãy xem nội dung giải thích để tìm hiểu thêm về các tham số này.

Giá trị của 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 trên độ nhiễu trên các giá trị tóm tắt (thảo luận thêm 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 nội dung giải thích. Ngoài ra, hãy tham khảo Ngân sách khoản đóng góp để biết thêm thông tin 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 để tạo báo cáo tóm tắt. Báo cáo tổng hợp có định dạng JSON và chứa danh sách các nội dung đóng góp đã mã hoá, mỗi nội dung 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 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ã các báo cáo và tạo báo cáo tóm tắt. Khoá mã hoá cho trình duyệt và khoá giải mã cho Dịch vụ tổng hợp do trình điều phối cấp và đóng vai trò là dịch vụ quản lý khoá. Trình điều phối lưu giữ danh sách các hàm băm nhị phân của hình ảnh dịch vụ để xác minh rằng phương thức gọi được phép nhận khoá giải mã.

Một ví dụ về báo cáo tổng hợp có chế độ gỡ lỗi đang bật:

  "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 trên trang chrome://private-aggregation-internals:

Đối với mục đích kiểm thử, bạn có thể sử dụng nút "Gửi báo cáo đã chọn" để gửi ngay báo cáo đến máy chủ.

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 công việc chứa lệnh gọi đến API Tổng hợp riêng tư, bằng cách sử dụng đường dẫn phổ biến được liệt kê:

• Đố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ò là bộ thu thập – nhận các báo cáo tổng hợp do máy khách gửi.

Sau đó, máy chủ sẽ báo cáo theo lô và gửi lô đến Dịch vụ tổng hợp. Tạo các lô dựa trên thông tin có trong tải trọng chưa mã hoá của báo cáo tổng hợp, chẳng hạn như trường shared_info. Mỗi lô nên chứa từ 100 báo cáo trở lên.

Bạn có thể quyết định phân lô theo ngày hoặc theo tuần. Chiến lược này rất linh hoạt và bạn có thể thay đổi chiến lược tạo lô cho các sự kiện cụ thể mà bạn mong đợi có nhiều lượt hiển thị hơn, ví dụ: các ngày trong năm khi dự kiến có nhiều lượt hiển thị hơn. Các 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à thời gian báo cáo theo lịch.

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áo cáo tóm tắt.

Để giải mã tải trọng báo cáo, Dịch vụ tổng hợp sẽ tìm nạp khoá giải mã từ trình điều phối. Dịch vụ này chạy trong một môi trường thực thi đáng tin cậy (TEE), giúp đảm bảo 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à vận hành dịch vụ, nhưng bạn sẽ không thấy được dữ liệu đang được xử lý 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 mình đã thu thập có thêm độ nhiễu. Bạn có thể yêu cầu báo cáo tóm tắt cho một tập hợp 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ị theo kiểu từ điển JSON. Mỗi cặp chứa:

• bucket: khoá tổng hợp dưới dạng một chuỗi số nhị phân. Nếu khoá tổng hợp được dùng là "123", thì bộ chứa sẽ 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 có sẵn đã thêm độ nhiễu.

Ví dụ:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Hiện tượng nhiễu và điều chỉnh theo 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 độ nhiễu một lần vào mỗi giá trị tóm tắt mỗi khi có yêu cầu báo cáo tóm tắt. Giá trị độ nhiễu được lấy ngẫu nhiên từ hàm phân phối xác suất Laplace. Mặc dù không nắm quyền kiểm soát trực tiếp cách thêm độ nhiễu, nhưng bạn có thể tác động đến tác động của độ nhiễu đối với dữ liệu đo lường.

Mức phân phối nhiễu là giống nhau bất kể tổng của tất cả giá trị tổng hợp. Do đó, các giá trị tổng hợp càng cao thì độ nhiễu càng ít có khả năng ảnh hưởng.

Ví dụ: giả sử hàm phân phối nhiễu có độ lệch chuẩn là 100 và được căn giữa bằng 0. Nếu giá trị của 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 sẽ chỉ bằng 0, 5% giá trị tổng hợp. Vì vậy, giá trị tổng hợp 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 hệ số tỷ lệ có thể giúp giảm độ nhiễu. Hệ số tỷ lệ biểu thị mức bạn muốn mở rộng một giá trị tổng hợp nhất định.

Việc tăng tỷ lệ các giá trị bằng cách chọn hệ số tỷ lệ lớn hơn sẽ làm giảm độ nhiễu tương đối. Tuy nhiên, điều này cũng khiến tổng các khoản đóng góp trên tất cả các nhóm đạt đến giới hạn ngân sách đóng góp nhanh hơn. Việc giảm tỷ lệ giá trị bằng cách chọn hằng số hệ số tỷ lệ nhỏ hơn sẽ làm tăng độ nhiễu tương đối, nhưng sẽ giảm nguy cơ đạt đến giới hạn ngân sách.

Để tính toán hệ số tỷ lệ thích hợp, hãy chia ngân sách đóng góp cho tổng giá trị tổng hợp tối đa của tất cả các khoá.

Xem Tài liệu về Ngân sách khoản đóng góp để 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 sẵn lòng.

• GitHub: Đọc tài liệu giải thích, đặt câu hỏi và tham gia thảo luận. * Hỗ trợ nhà phát triển: Đặt câu hỏi và tham gia thảo luận về kho lưu trữ Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư. * Tham gia nhóm Shared Storage API và nhóm Protected Audience API để xem thông báo mới nhất liên quan đến tính năng Tổng hợp riêng tư.