Tạo báo cáo dữ liệu tổng hợp bằng cách sử dụng dữ liệu của Protected Audience và dữ liệu trên nhiều trang web từ Bộ nhớ dùng chung.
Để cung cấp các tính năng quan trọng mà web sử dụng, tính năng Tổng hợp riêng tư API được xây dựng để tổng hợp và báo cáo về dữ liệu trên nhiều trang web trong một theo cách bảo đảm quyền riêng tư.
Trạng thái triển khai
Đề xuất | Trạng thái |
---|---|
Ngăn chặn các báo cáo không hợp lệ về API Tổng hợp riêng tư nhờ tính năng xác minh báo cáo cho Bộ nhớ dùng chung Giải thích |
Có trong Chrome |
Khả năng sử dụng chế độ gỡ lỗi Tổng hợp riêng tư tuỳ thuộc vào điều kiện sử dụng 3PC Vấn đề trong GitHub |
Có trong Chrome M119 |
Giảm độ trễ cho báo cáo Người giải thích |
Có trong Chrome M119 |
Hỗ trợ API tổng hợp riêng tư và Dịch vụ tổng hợp dành cho Google Cloud Người giải thích |
Có trong Chrome M121 |
Khoảng đệm cho các tải trọng báo cáo tổng hợp Người giải thích |
Có trong Chrome M119 |
Chế độ gỡ lỗi Tổng hợp riêng tư hiện đã được cung cấp cho tính năng báo cáo AuctionReport Buyers Người giải thích |
Dự kiến có trong Chrome M123 |
Hỗ trợ mã lọc Người giải thích |
Dự kiến có trong Chrome M128 |
API Tổng hợp riêng tư là gì
API tổng hợp riêng tư cho phép nhà phát triển tạo báo cáo dữ liệu tổng hợp với dữ liệu từ Protected Audience API và dữ liệu trên nhiều trang web từ Bộ nhớ dùng chung.
Chức năng chính của API này là contributeToHistogram()
. Thao tác biểu đồ cho phép bạn tổng hợp dữ liệu
trên số người dùng trong mỗi bộ chứa (được gọi trong API là khoá tổng hợp) mà bạn xác định.
Lệnh gọi biểu đồ của bạn tích luỹ các giá trị và trả về kết quả tổng hợp có độ nhiễu trong
dưới dạng báo cáo tóm tắt. Ví dụ: báo cáo có thể cho thấy số lượng
các trang web mà mỗi người dùng đã xem nội dung của bạn hoặc gặp lỗi trong tập lệnh của bên thứ ba. Thao tác này được thực hiện trong worklet của API khác.
Ví dụ: nếu trước đây bạn đã ghi lại dữ liệu nhân khẩu học và địa lý trong Bộ nhớ dùng chung, thì bạn có thể sử dụng API tổng hợp riêng tư để tạo biểu đồ cho bạn biết khoảng bao nhiêu người dùng ở Thành phố New York đã xem nội dung của bạn qua trang web. Để tổng hợp cho hoạt động đo lường này, bạn có thể mã hoá phương diện địa lý thành khoá tổng hợp và đếm số người dùng trong giá trị tổng hợp.
Khái niệm chính
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.
Các báo cáo tổng hợp được gửi đến máy chủ của bạn để thu thập và phân lô. Các báo cáo theo lô sẽ được Dịch vụ tổng hợp xử lý sau và tạo báo cáo tóm tắt.
Xem tài liệu Kiến thức cơ bản về API tổng hợp riêng tư để tìm hiểu thêm về các khái niệm chính liên quan đến API tổng hợp riêng tư.
Điểm khác biệt so với Báo cáo phân bổ
API tổng hợp riêng tư có nhiều điểm tương đồng với Attribution Reporting API. Báo cáo phân bổ là một API độc lập được thiết kế để đo lường lượt chuyển đổi, trong khi tính năng Tổng hợp riêng tư được xây dựng để đo lường trên nhiều trang web cùng với các API như Protected Audience API và Bộ nhớ dùng chung. Cả hai API này đều tạo ra các báo cáo tổng hợp mà dịch vụ phụ trợ của Dịch vụ tổng hợp sử dụng để tạo các báo cáo tóm tắt.
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 đơn lẻ trên nhiều trang web.
Kiểm thử API này
Để kiểm thử cục bộ API Tổng hợp riêng tư, hãy bật tất cả API quyền riêng tư trong quảng cáo trong chrome://settings/adPrivacy
.
Đọc thêm về việc kiểm thử trong tính năng thử nghiệm và tham gia.
Sử dụng bản minh hoạ
Bạn có thể truy cập bản minh hoạ của API tổng hợp riêng tư cho Bộ nhớ dùng chung tại goo.gle/shared-storage-demo và mã này có trên GitHub. Bản minh hoạ triển khai các thao tác phía máy khách và tạo báo cáo tổng hợp được gửi đến máy chủ của bạn.
Bản minh hoạ về API Tổng hợp riêng tư cho Protected Audience API sẽ được xuất bản trong tương lai.
Trường hợp sử dụng
Tổng hợp riêng tư là một API đa năng để đo lường trên nhiều trang web. API này có thể dùng trong các công việc liên quan đến Bộ nhớ dùng chung và Protected Audience API. Bước đầu tiên là quyết định cụ thể thông tin nào bạn muốn thu thập. Các điểm dữ liệu đó là cơ sở của khoá tổng hợp.
Có bộ nhớ dùng chung
Bộ nhớ dùng chung cho phép bạn đọc và ghi dữ liệu trên nhiều trang web trong một môi trường an toàn để ngăn chặn tình trạng rò rỉ, còn API tổng hợp riêng tư cho phép bạn đo lường dữ liệu trên nhiều trang web được lưu trữ trong Bộ nhớ dùng chung.
Đo lường phạm vi tiếp cận người dùng riêng biệt
Bạn nên đo lường số lượng người dùng riêng biệt đã xem nội dung của họ. API tổng hợp riêng tư có thể đưa ra câu trả lời như "Có khoảng 317 người dùng riêng biệt đã xem Content ID 861".
Bạn có thể đặt cờ trong Bộ nhớ dùng chung để biểu thị việc người dùng đã xem nội dung hay chưa. Trong lần truy cập đầu tiên khi cờ này không tồn tại, một lệnh gọi đến tính năng Tổng hợp riêng tư sẽ được thực hiện, sau đó cờ sẽ được đặt. Trong các lần truy cập tiếp theo của người dùng, bao gồm cả các lượt truy cập trên nhiều trang web, bạn có thể kiểm tra Bộ nhớ dùng chung và bỏ qua việc gửi báo cáo cho tính năng Tổng hợp riêng tư nếu cờ này đã được đặt. Để tìm hiểu thêm về các phương pháp triển khai những phương pháp đo lường này, hãy xem sách trắng về phạm vi tiếp cận của chúng tôi.
Đo lường thông tin nhân khẩu học
Bạn có thể muốn đo lường nhân khẩu học của những người dùng đã xem nội dung của bạn trên các trang web khác nhau.
Tính năng Tổng hợp riêng tư có thể đưa ra câu trả lời, chẳng hạn như "Khoảng 317 người dùng duy nhất là từ 18 đến 45 tuổi và đến từ Đức". Sử dụng Bộ nhớ dùng chung để truy cập dữ liệu nhân khẩu học từ ngữ cảnh bên thứ ba. Sau này, bạn có thể tạo báo cáo bằng tính năng Tổng hợp riêng tư bằng cách mã hoá phương diện nhóm tuổi và quốc gia trong khoá tổng hợp.
Đo lường tần suất từ K+
Bạn có thể muốn đo lường số người dùng đã xem một đoạn nội dung hoặc quảng cáo ít nhất K lần trên một trình duyệt nhất định, cho giá trị đã chọn trước là K.
Tính năng Tổng hợp riêng tư có thể đưa ra câu trả lời như "Khoảng 89 người dùng đã xem Content ID 581 ít nhất 3 lần". Bạn có thể tăng bộ đếm trong Bộ nhớ dùng chung từ các trang web khác nhau và bộ đếm có thể được đọc trong một worklet. Khi số lượng đã đạt đến K, bạn có thể gửi báo cáo thông qua tính năng Tổng hợp riêng tư.
Sử dụng Protected Audience API
Protected Audience API hỗ trợ các trường hợp sử dụng đối tượng nhắm mục tiêu lại và tuỳ chỉnh, còn tính năng Tổng hợp riêng tư cho phép bạn báo cáo các sự kiện từ các luồng công việc của người mua và người bán. Bạn có thể sử dụng API này cho các công việc như đo lường việc phân phối giá thầu trong phiên đấu giá.
Từ một worklet Protected Audience API, bạn có thể trực tiếp tổng hợp dữ liệu của mình bằng contributeToHistogram()
và báo cáo dữ liệu dựa trên một điều kiện kích hoạt bằng contributeToHistogramOnEvent()
– một tiện ích đặc biệt của Protected Audience API.
Hàm có sẵn
Các hàm sau có trong đối tượng privateAggregation
có trong các Worklet Bộ nhớ dùng chung và Protected Audience API.
contributeToHistogram()
Bạn có thể gọi privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
, trong đó khoá tổng hợp là bucket
và giá trị tổng hợp là value
. Đối với tham số bucket
, bạn phải có BigInt
. Đối với tham số value
, cần phải có một Số nguyên.
Dưới đây là ví dụ về cách gọi bộ nhớ dùng chung trong Bộ nhớ dùng chung để đo lường phạm vi tiếp cận:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
Đoạn mã ví dụ ở trên sẽ gọi tính năng Tổng hợp riêng tư bất cứ khi nào nội dung iframe trên nhiều trang web được tải. Mã iframe tải worklet và worklet gọi API tổng hợp riêng tư với mã nội dung được chuyển đổi thành khoá tổng hợp (bộ chứa).
contributeToHistogramOnEvent()
Riêng trong các chương trình công việc Protected Audience API, chúng tôi cung cấp một cơ chế dựa trên điều kiện kích hoạt để chỉ gửi báo cáo khi một sự kiện nhất định xảy ra. Hàm này cũng cho phép nhóm và giá trị phụ thuộc vào các tín hiệu chưa có sẵn tại thời điểm đó trong phiên đấu giá.
Phương thức privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
lấy một eventType
chỉ định sự kiện kích hoạt và contribution
sẽ được gửi khi sự kiện đó được kích hoạt. Sự kiện kích hoạt có thể đến từ chính phiên đấu giá sau khi phiên đấu giá kết thúc, chẳng hạn như sự kiện thắng/thua trong phiên đấu giá hoặc có thể đến từ một khung bảo vệ hiển thị quảng cáo.
Để gửi báo cáo cho các sự kiện đấu giá, bạn có thể sử dụng hai từ khoá đặt trước là reserved.win
, reserved.loss
và reserved.always
. Để gửi báo cáo do một sự kiện kích hoạt từ một khung bảo vệ, hãy xác định một loại sự kiện tuỳ chỉnh. Để kích hoạt sự kiện từ một khung bảo vệ, hãy sử dụng phương thức fence.reportEvent()
có trong API Báo cáo quảng cáo khung bảo vệ.
Ví dụ sau đây gửi báo cáo lượt hiển thị khi sự kiện thắng phiên đấu giá được kích hoạt, đồng thời gửi báo cáo lượt nhấp nếu sự kiện click
được kích hoạt từ khung bảo vệ đã hiển thị quảng cáo. Hai giá trị này có thể được sử dụng để tính tỷ lệ nhấp.
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
Xem nội dung giải thích về Báo cáo tổng hợp riêng tư mở rộng để tìm hiểu thêm.
enableDebugMode()
Mặc dù bạn vẫn có thể sử dụng cookie của bên thứ ba, nhưng chúng tôi sẽ cung cấp một cơ chế tạm thời để bạn có thể gỡ lỗi và kiểm thử dễ dàng hơn bằng cách bật chế độ gỡ lỗi. Báo cáo gỡ lỗi rất hữu ích trong việc so sánh các kết quả đo lường dựa trên cookie với kết quả đo lường của tính năng Tổng hợp riêng tư, đồng thời giúp bạn nhanh chóng xác thực quy trình tích hợp API.
Việc gọi privateAggregation.enableDebugMode()
trong worklet sẽ bật chế độ gỡ lỗi để khiến các báo cáo tổng hợp thêm phần tải trọng (văn bản rõ ràng) chưa mã hoá. Sau đó, bạn có thể xử lý các tải trọng này bằng công cụ kiểm tra cục bộ Dịch vụ tổng hợp.
Chế độ gỡ lỗi chỉ dành cho người gọi được phép truy cập
cookie của bên thứ ba. Nếu phương thức gọi không có quyền truy cập vào cookie của bên thứ ba,
enableDebugMode()
sẽ tự động không thành công. Điều này có nghĩa là khi bên thứ ba
cookie không được dùng nữa, chế độ gỡ lỗi sẽ không còn hoạt động nữa.
Bạn cũng có thể đặt khoá gỡ lỗi bằng cách gọi privateAggregation.enableDebugMode({ <debugKey: debugKey> })
, trong đó BigInt
có thể được dùng làm khoá gỡ lỗi. Bạn có thể sử dụng khoá gỡ lỗi để liên kết dữ liệu của phương pháp đo lường dựa trên cookie và dữ liệu của kết quả đo lường Tổng hợp riêng tư.
Bạn chỉ có thể gọi lệnh này một lần cho mỗi ngữ cảnh. Mọi lệnh gọi tiếp theo sẽ gửi một ngoại lệ.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Xác minh báo cáo
Đối với Bộ nhớ dùng chung, bạn có thể xác minh các báo cáo tổng hợp mà bạn nhận được là hợp lệ bằng cách thêm mã nhận dạng theo bối cảnh vào lệnh gọi hoạt động của bộ nhớ dùng chung. Mã này sẽ được đính kèm vào báo cáo đã gửi. Sau này, bạn có thể dùng mã này để xác minh rằng báo cáo được gửi từ hoạt động của bộ nhớ dùng chung.
Để tìm hiểu thêm, hãy xem tài liệu giải thích về quy trình xác minh báo cáo.
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 phần giải thích, nêu câu hỏi và tham gia thảo luận.
- Hỗ trợ dành cho 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 nhóm API Bộ nhớ dùng chung và nhóm Protected Audience API để nhận 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ư.