Tổng quan về API tổng hợp riêng tư

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, API Tổng hợp riêng tư được xây dựng để tổng hợp và báo cáo về dữ liệu trên nhiều trang web 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 API tổng hợp riêng tư không hợp lệ bằng quy trình xác minh báo cáo cho Bộ nhớ dùng chung
Giải thích		 Hiện có trên Chrome
Khả năng sử dụng của chế độ gỡ lỗi Tổng hợp riêng tư phụ thuộc vào việc 3 máy tính có đủ điều kiện hay không
Vấn đề về GitHub		 Có trên Chrome M119
Giảm độ trễ báo cáo
Nội dung giải thích		 Có trên Chrome M119
Hỗ trợ API tổng hợp riêng tư và Dịch vụ tổng hợp của Google Cloud
Giải thích		 Có trên Chrome M121
Khoảng đệm cho các tải trọng báo cáo tổng hợp
Giải thích		 Có trên Chrome M119
Bạn có thể sử dụng chế độ gỡ lỗi Tổng hợp riêng tư cho báo cáo AuctionReportPurchases của người mua
Giải thích		 Dự kiến có trong Chrome M123
Hỗ trợ mã lọc
Nội dung giải thích		 Dự kiến ra mắt đầu tiên trên Chrome vào quý 2 năm 2024.

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 bằng dữ liệu của Protected Audience API và dữ liệu trên nhiều trang web từ Bộ nhớ dùng chung.

API này hiện cung cấp một thao tác là sendHistogramReport(), nhưng sau này có thể chúng tôi sẽ hỗ trợ nhiều thao tác khác. Toán tử biểu đồ cho phép bạn tổng hợp dữ liệu về người dùng trong mỗi nhóm (đượ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 ở dạng báo cáo tóm tắt. Ví dụ: báo cáo có thể hiển thị số lượng trang web mà mỗi người dùng đã xem nội dung của bạn hoặc phát hiện một 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 trên nhiều trang web. Để tổng hợp dữ liệu đo lường này, bạn có thể mã hoá phương diện địa lý vào khoá tổng hợp và tính 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.

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ô. Dịch vụ tổng hợp sẽ xử lý báo cáo theo 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ư.

Sự khác biệt 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 API báo cáo phân bổ. 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 đều tạo các báo cáo tổng hợp mà hệ thống phụ trợ Dịch vụ tổng hợp sử dụng để tạo báo cáo tóm tắt.

Báo cáo phân bổ liên kết dữ liệu được thu thập từ một sự kiện hiển thị và một sự kiện chuyển đổi, xảy ra ở những 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.

Kiểm thử API này

Bạn có thể kiểm thử cục bộ API Tổng hợp riêng tư bằng cách bật cờ thử nghiệm API Quảng cáo trên Hộp cát về quyền riêng tư tại chrome://flags/#privacy-sandbox-ads-apis.

Đặt thử nghiệm API Quảng cáo trên Hộp cát về quyền riêng tư thành bật để sử dụng các API này
Đặt thử nghiệm API Quảng cáo trên Hộp cát về quyền riêng tư thành bật để sử dụng các API này

Đọc thêm về hoạt động kiểm thử trong thử nghiệm và tham gia.

Sử dụng bản minh hoạ

Bạn có thể truy cập vào 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 hoạt động 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ạ của 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 và có thể dùng trong các công việc 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. Những điểm dữ liệu đó là cơ sở cho các khoá tổng hợp của bạn.

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ỉ. 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

Có thể bạn muốn đo lường số lượng người dùng duy nhấ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ư "Khoảng 317 người dùng riêng biệt đã nhìn thấy Content ID 861".

Bạn có thể đặt cờ trong Bộ nhớ dùng chung để cho biết 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, lệnh gọi đến tính năng Tổng hợp riêng tư sẽ được thực hiện và sau đó cờ này được đặt. Trong những lần người dùng truy cập tiếp theo (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 bạn đặt cờ hiệu.

Đo lường thông tin nhân khẩu học

Bạn có thể muốn đo lường thông tin nhân khẩu học của người dùng đã xem nội dung của bạn trên các trang web khác nhau.

Tổng hợp riêng tư có thể cung cấp câu trả lời, chẳng hạn như "Khoảng 317 người dùng riêng biệt trong độ tuổi từ 18 đến 45 và đến từ Đức". Sử dụng Bộ nhớ dùng chung để truy cập vào dữ liệu nhân khẩu học từ bối cảnh của bên thứ ba. Sau này, bạn có thể tạo một báo cáo bằng tính năng Tổng hợp riêng tư bằng cách mã hoá các phương diện nhóm tuổi và quốc gia trong khoá tổng hợp.

Đo tần số K+

Bạn có thể muốn đo lường số người dùng đã xem một 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, với giá trị K đã chọn trước.

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ộ đếm có thể tăng lên trong Bộ nhớ dùng chung từ nhiều trang web và 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ư.

Bằng Protected Audience API

Protected Audience API hỗ trợ các trường hợp sử dụng đối tượng tuỳ chỉnh và nhắm mục tiêu lại, 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ông việc của người mua và người bán. Bạn có thể sử dụng API cho các tác vụ như đo lường việc phân phối giá thầu trong phiên đấu giá.

Từ một worklet của Protected Audience API, bạn có thể tổng hợp dữ liệu trực tiếp bằng sendHistogramReport() và báo cáo dữ liệu dựa trên một điều kiện kích hoạt bằng reportContributionForEvent() (một tiện ích đặc biệt của Protected Audience API).

Hàm có sẵn

Các hàm sau đây 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, bạn phải có một Số nguyên.

Dưới đây là ví dụ về cách gọi địa chỉ này 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 this.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 this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Ví dụ về mã ở 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 công việc, công việc sẽ 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()

Chỉ trong các bộ công việc Protected Audience API, chúng tôi cung cấp 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.reportContributionForEvent(eventType, contribution) lấy eventType chỉ định sự kiện kích hoạt và gửi contribution 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 hoặc 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 được kích hoạt bởi một sự kiện trong khung bảo vệ, hãy xác định loại sự kiện tuỳ chỉnh. Để kích hoạt sự kiện từ một khung được 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 sẽ gửi báo cáo lượt hiển thị khi sự kiện chiến thắng trong 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 được bảo vệ đã hiển thị quảng cáo. Bạn có thể sử dụng hai giá trị này để 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 thông tin 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 cho phép 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 khi so sánh kết quả đo lường dựa trên cookie với kết quả đo lường Tổng hợp riêng tư, đồng thời cho phép bạn nhanh chóng xác thực việc 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 bao gồm tải trọng (cleartext) 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ộ của Dịch vụ tổng hợp.

Chế độ gỡ lỗi chỉ dành cho các phương thức gọi được phép truy cập vào 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, thì enableDebugMode() sẽ tự động không thành công. Điều này có nghĩa là khi cookie của bên thứ ba 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 đó có thể dùng BigInt 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 một phép đo lường dựa trên cookie với dữ liệu của phương pháp đo lường Tổng hợp riêng tư. Bạn chỉ có thể gọi các hành động này một lần cho mỗi ngữ cảnh. Mọi cuộc gọi tiếp theo sẽ bị bỏ qua.

// 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ã ngữ cảnh vào lệnh gọi hoạt động bộ nhớ dùng chung. Mã này sẽ được đính kèm vào báo cáo đã gửi và sau này, bạn có thể sử dụng mã đó để xác minh rằng báo cáo được gửi từ hoạt động sử dụng bộ nhớ dùng chung.

Tính năng này hiện có sẵn để thử nghiệm trong Chrome M114+. Hiện chưa xác minh báo cáo cho Protected Audience API.

Để tìm hiểu thêm, hãy xem phần 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 sôi nổi 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.