Trang này được dịch bởi Cloud Translation API.

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

Các khái niệm chính của Private Aggregation API

Tài liệu này dành cho đối tượng nào?

Private Aggregation API (API tổng hợp riêng tư) cho phép thu thập dữ liệu tổng hợp từ 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ẻ tại đây rất quan trọng đối với nhà phát triển xây dựng các chức năng báo cáo trong Shared Storage và Protected Audience API.

Nếu bạn là một nhà phát triển đang xây dựng một 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 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 tập hợp điểm dữ liệu được xác định trước. Ví dụ: bạn có thể muốn thu thập một nhóm dữ liệu vị trí mà 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 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 vào 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ì 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 hợ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 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 làm việc của tính năng 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. Sau đó, Dịch vụ tổng hợp sẽ xử lý các báo cáo theo lô và tạo một báo cáo tóm tắt.

Dữ liệu di chuyển từ ứng dụng đến trình thu thập, sau đó chuyển đến mục Tổng hợp
Dịch vụ tạo 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ừ các ứng dụng và phân nhóm các báo cáo đó để 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, 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 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 biết thêm thông tin chi tiết, 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 người dùng đã xem tiện ích của bạn. Bạn 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 ở 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
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 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 rồi chuyển đổi thành giá trị BigInt của 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 xem SubtleCrypto.digest() trên MDN.

Ví dụ sau đây mô tả cách bạn có thể tạo khoá bộ chứa từ một giá trị được 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

Giá trị tổng hợp

Các giá trị tổng hợp được cộng lại theo khoá trên 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 được đưa ra trước đó: "Có bao nhiêu người dùng đã xem 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, tức là tổng của tất cả giá trị tổng hợp cho 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 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ế, giá trị tổng hợp có thể được điều chỉnh theo tỷ lệ để cải thiện tỷ lệ tín hiệu 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 mà một cá nhân có thể đóng góp sẽ bị giới hạn.

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 phân theo nguồn gốc của mỗi worklet, theo ngày và riêng biệt cho Protected Audience API và worklet 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ố L₁ và là được đặt thành 2¹⁶ (65.536)/10 phút mỗi 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 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 trên tạp âm trên các giá trị tóm tắt (sẽ được thảo luận thêm trong phần Tạp âm và điều chỉnh theo 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.

Giới hạn đóng góp cho mỗi báo cáo

Tuỳ thuộc vào phương thức gọi, hạn mức đóng góp có thể khác nhau. Hiện tại, các báo cáo được tạo cho phương thức gọi API Bộ nhớ dùng chung bị giới hạn ở mức 20 lượt đóng góp trên mỗi báo cáo. Mặt khác, phương thức gọi Protected Audience API bị giới hạn ở mức 100 lượt đóng góp cho mỗi báo cáo. Những giới hạn này được chọn để cân bằng số lượng nội dung đóng góp có thể được nhúng cùng với kích thước của tải trọng.

Đối với Bộ nhớ dùng chung, các nội dung đóng góp được thực hiện trong một thao tác run() hoặc selectURL() sẽ được phân thành một báo cáo. Đối với Protected Audience, số lượt đóng góp đã đóng góp theo một nguồn gốc duy nhất trong phiên đấu giá sẽ được nhóm lại với nhau.

Nội dung đóng góp có khoảng đệm

Các nội dung đóng góp được sửa đổi thêm bằng tính năng khoảng đệm. Việc thêm vào tải trọng giúp bảo vệ thông tin về số lượng đóng góp thực tế được nhúng trong báo cáo tổng hợp. Khoảng đệm tăng tải trọng bằng các đóng góp null (tức là có giá trị 0) để đạt được một độ dài cố định.

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. Báo cáo tổng hợp có định dạng JSON và chứa danh sách đóng góp đã mã hoá, mỗi đóng góp là một cặp {aggregation key, aggregatable value}. Báo cáo tổng hợp được gửi với độ trễ ngẫu nhiên lên đến một giờ.

Các khoản đóng góp được mã hoá và không thể đọ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á. 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ã.

Ví dụ về báo cáo tổng hợp có bật chế độ 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:

ảnh chụp màn hình trang nội bộ của Private Aggregation API

Đối với mục đích thử nghiệm, bạn có thể sử dụng nút "Gửi báo cáo đã chọn" để gửi báo cáo đến 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 sẽ 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ư, 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à trình thu thập — nhận các báo cáo tổng hợp được gửi từ ứng dụng.

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. Các lô phải bao gồm 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 lên lịch báo cáo.

Dịch vụ tổng hợp

Dịch vụ này chạy trong TEE, giải mã các báo cáo tổng hợp và thêm nhiễu để tạo báo cáo tóm tắt cuối cùng.

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ụ 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ù sở hữu và vận hành dịch vụ, nhưng bạn sẽ không thể xem 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ỗi 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 sử 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 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 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. Các giá trị nhiễu được lấy ngẫu nhiên từ một phân phối xác suất Laplace. Mặc dù không kiểm soát trực tiếp cách tạp âm được thêm vào, nhưng bạn có thể tác động đến mức độ ảnh hưởng của tạp âm đối với dữ liệu đo lường.

Phân phối nhiễu giống nhau bất kể tổng của tất cả các giá trị tổng hợp. 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ử phân phối nhiễu có độ lệch chuẩn là 100 và tập trung tại 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. Tuy nhiên, nếu giá trị tổng hợp là 20.000, thì độ lệch chuẩn của nhiễu sẽ chỉ là 0,5% của 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 của bạn 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 điều chỉnh theo tỷ lệ một giá trị tổng hợp nhất định.

Độ nhiễu không đổi bất kể 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 khiến tổng số đóng góp trên tất cả các bộ chứa đạt đến giới hạn 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.

Điều chỉnh tỷ lệ giá trị tổng hợp theo ngân sách đóng góp.

Để 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á.

Hãy xem tài liệu về Ngân sách đóng góp để tìm hiểu thêm.

Tham gia và chia sẻ ý kiến phản hồi

API Tổng hợp riêng tư đang được 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 kho lưu trữ Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư. * 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ư.