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 dựa vào, API tổng hợp riêng tư đã được xây dựng nhằm 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 từ Protected Audience API và dữ liệu trên nhiều trang web của Bộ nhớ dùng chung.

API này hiện cung cấp một thao tác là sendHistogramReport(), nhưng có thể sẽ hỗ trợ thêm nhiều thao tác khác trong tương lai. Thao tác biểu đồ cho phép bạn tổng hợp dữ liệu giữa nhiều người dùng trong từng bộ chứa (trong API là khoá tổng hợp) mà bạn xác định. Lệnh gọi biểu đồ của bạn sẽ tích luỹ các giá trị và trả về kết quả tổng hợp có độ nhiễu dưới dạng báo cáo tóm tắt. Ví dụ: báo cáo này có thể cho biết 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 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ượt 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.

Đo lường 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 tần suấ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 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 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 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);

Đ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.reportContributionForEvent(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 những 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ực hiện được. Đ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 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ể 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.

Bạn hiện có thể thử nghiệm tính năng này trong Chrome M114 trở lên. Tính năng xác minh báo cáo cho Protected Audience API hiện chưa được hỗ trợ cho quá trình thử nghiệm.

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