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 từ Protected Audience và dữ liệu trên nhiều trang web từ Shared Storage.

Để cung cấp các tính năng quan trọng mà web dựa vào, Private Aggregation API được tạo ra để tổng hợp và báo cáo 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

Private Aggregation API là gì

Private Aggregation API 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 từ Shared Storage.

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

Ví dụ: nếu trước đây đã ghi lại dữ liệu nhân khẩu học và địa lý trong Shared Storage, bạn có thể sử dụng Private Aggregation API để tạo một biểu đồ tần suất cho biết số lượng 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 cho phép đo này, bạn có thể mã hoá phương diện vị trí địa lý vào khoá tổng hợp và tính số người dùng trong giá trị có thể tổng hợp.

Khái niệm chính

Khi bạn gọi Private Aggregation API bằng một khoá tổng hợp và một giá trị có thể tổng hợp, trình duyệt sẽ tạo một báo cáo có thể tổng hợp.

Các báo cáo có thể tổng hợp sẽ được gửi đến máy chủ của bạn để thu thập và xử lý theo lô. Sau đó, Aggregation Service sẽ xử lý các báo cáo theo lô và tạo ra một báo cáo tóm tắt.

Hãy xem tài liệu Thông tin cơ bản về Private Aggregation API để tìm hiểu thêm về các khái niệm chính liên quan đến Private Aggregation API.

Khác biệt so với Attribution Reporting

Private Aggregation API có nhiều điểm tương đồng với Attribution Reporting API. Attribution Reporting là một API độc lập được thiết kế để đo lường lượt chuyển đổi, trong khi Private Aggregation đượ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à Shared Storage. Cả hai API này đều tạo ra các báo cáo có thể tổng hợp được sử dụng bởi phần phụ trợ của Aggregation Service để tạo báo cáo tóm tắt.

Attribution Reporting 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 vào những thời điểm khác nhau). 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

Để kiểm thử Private Aggregation API cục bộ, hãy bật tất cả Ad privacy API trong chrome://settings/adPrivacy.

Đọc thêm về việc thử nghiệm 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ạ Private Aggregation API cho Shared Storage tại goo.gle/shared-storage-demo và mã này có trên GitHub. Bản minh hoạ này triển khai các thao tác phía máy khách và tạo ra một báo cáo có thể tổng hợp được gửi đến máy chủ của bạn.

Bản minh hoạ Private Aggregation API cho Protected Audience API sẽ được xuất bản trong tương lai.

Trường hợp sử dụng

Private Aggregation là một API đa dụng để đo lường trên nhiều trang web và có thể được dùng trong các worklet Shared Storage và Protected Audience API. Bước đầu tiên là quyết định cụ thể thông tin 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

Shared Storage 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ỉ, đồng thời Private Aggregation API cho phép bạn đo lường dữ liệu trên nhiều trang web được lưu trữ trong Shared Storage.

Đo lường phạm vi tiếp cận người dùng riêng biệt

Bạn có thể muốn đo lường số người dùng riêng biệt đã xem nội dung của họ. Private Aggregation API có thể cung cấp 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 một cờ trong Bộ nhớ dùng chung để cho biết liệu người dùng đã xem nội dung hay chưa. Trong lần truy cập đầu tiên mà cờ không tồn tại, một lệnh gọi đến Private Aggregation sẽ được thực hiện và sau đó cờ được đặt. Trong những lần truy cập tiếp theo của người dùng (kể cả lượt truy cập trên nhiều trang web), bạn có thể kiểm tra Shared Storage và bỏ qua việc gửi báo cáo đến Private Aggregation nếu cờ được đặt. Để tìm hiểu thêm về các phương thức 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 thông tin nhân khẩu học của những người dùng đã xem nội dung của bạn trên nhiều trang web.

Private Aggregation 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 ở độ tuổi từ 18 đến 45 và đến từ Đức". Sử dụng Shared Storage để truy cập vào dữ liệu nhân khẩu học từ một bối cảnh của bên thứ ba. Sau này, bạn có thể tạo báo cáo bằng Private Aggregation 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 K+

Bạn có thể muốn đo lường số lượng 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 được chọn trước.

Tính năng Tổng hợp riêng tư có thể cung cấp 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ừ nhiều trang web và có thể đọc bộ đếm trong một worklet. Khi số lượng đạt đến K, bạn có thể gửi báo cáo bằng Private Aggregation.

Phân bổ đa điểm tiếp xúc

Phân bổ trong hoạt động tiếp thị là một phương pháp mà nhà quảng cáo sử dụng để xác định mức độ đóng góp của các chiến thuật tiếp thị và các lượt tương tác tiếp theo với quảng cáo vào doanh số bán hàng hoặc lượt chuyển đổi.

Với Protected Audience API

Protected Audience API cho phép các trường hợp sử dụng đối tượng tuỳ chỉnh và hoạt động tái tiếp thị, còn Private Aggregation cho phép bạn báo cáo các sự kiện từ các worklet của người mua và người bán. Bạn có thể dùng API này cho các tác vụ như đo lường mức phân phối giá thầu trong phiên đấu giá.

Từ một worklet Protected Audience API, bạn có thể tổng hợp dữ liệu trực tiếp bằng cách sử dụ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 cách sử dụng contributeToHistogramOnEvent(). Đây là một tiện ích đặc biệt cho Protected Audience API.

Các hàm có sẵn

Các hàm sau đây có trong đối tượng privateAggregation có trong các worklet Shared Storage API 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ị có thể 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 nhập một số nguyên.

Sau đây là ví dụ về cách gọi API 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 sharedStorage.get(key) === 'true';

    // Don't 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);

Ví dụ về mã trước đó sẽ gọi Private Aggregation 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 Private Aggregation API bằng mã nhận dạng nội dung được chuyển đổi thành khoá tổng hợp (nhóm).

contributeToHistogramOnEvent()

Chỉ trong các worklet 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 nếu 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ó 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 hoặc thua trong phiên đấu giá, hoặc có thể đến từ một khung được phân vùng đã hiển thị quảng cáo.

Để gửi báo cáo về các sự kiện đấu giá, bạn có thể sử dụng 2 từ khoá dành riêng là reserved.win, reserved.loss và reserved.always. Để gửi báo cáo do một sự kiện trong khung được rào kích hoạt, 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 được bao bọc, hãy sử dụng phương thức fence.reportEvent() có trong Fenced Frames Ads Reporting API.

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 và gửi báo cáo lượt nhấp nếu sự kiện click được kích hoạt từ khung được rào chắn đã hiển thị quảng cáo. Bạn có thể 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
  });

Hãy 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ù cookie của bên thứ ba vẫn có sẵn, nhưng chúng tôi sẽ cung cấp một cơ chế tạm thời giúp bạn gỡ lỗi và thử nghiệm 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 phép đo dựa trên cookie với các phép đo Private Aggregation, đồ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 có thể tổng hợp bao gồm tải trọng chưa mã hoá (văn bản thuần tuý). Sau đó, bạn có thể xử lý các tải trọng này bằng công cụ kiểm thử cục bộ của Dịch vụ tổng hợp.

Chế độ gỡ lỗi chỉ dành cho những đối tượng 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.

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. Khoá gỡ lỗi có thể được dùng để liên kết dữ liệu từ một phép đo dựa trên cookie và dữ liệu từ phép đo Private Aggregation.

Bạn chỉ có thể gọi các phương thức này một lần cho mỗi ngữ cảnh. Mọi lệnh gọi tiếp theo sẽ tạo ra 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

Private Aggregation API cho phép đo lường trên nhiều trang web mà vẫn bảo vệ quyền riêng tư của người dùng. Tuy nhiên, đối tượng xấu có thể tìm cách thao túng độ chính xác của các chỉ số này. Để ngăn chặn điều này, bạn có thể sử dụng mã nhận dạng bối cảnh để xác minh tính xác thực của báo cáo.

Việc đặt mã nhận dạng bối cảnh giúp đảm bảo rằng dữ liệu chính xác khi đóng góp vào kết quả tổng hợp cuối cùng. Bạn có thể làm điều này bằng cách:

• Ngăn chặn báo cáo không hợp lệ hoặc không xác thực: Xác minh rằng báo cáo được tạo thông qua các lệnh gọi API hợp lệ và xác thực, khiến những đối tượng xấu khó tạo ra báo cáo giả mạo.
• Ngăn chặn việc phát lại báo cáo: Phát hiện và từ chối mọi nỗ lực sử dụng lại các báo cáo cũ, đảm bảo rằng mỗi báo cáo chỉ được đóng góp một lần vào kết quả tổng hợp.

Bộ nhớ dùng chung

Khi sử dụng Shared Storage để chạy một thao tác có thể gửi một báo cáo có thể tổng hợp, bạn có thể đặt một mã nhận dạng không dự đoán được bên ngoài worklet.

Mã này được nhúng trong báo cáo được tạo từ worklet. Bạn có thể chỉ định giá trị này khi gọi phương thức Bộ nhớ dùng chung run() hoặc selectURL(), trong đối tượng lựa chọn theo khoá privateAggregationConfig.

Ví dụ:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Sau khi đặt mã nhận dạng này, bạn có thể dùng mã nhận dạng đó để xác minh rằng báo cáo được gửi từ thao tác Bộ nhớ dùng chung. Để ngăn chặn rò rỉ thông tin, chính xác một báo cáo được gửi cho mỗi thao tác Shared Storage (ngay cả khi không có đóng góp nào), bất kể số lượng lệnh gọi contributeToHistogram().

Private Aggregation API gửi các báo cáo có thể tổng hợp với độ trễ ngẫu nhiên lên đến một giờ. Tuy nhiên, việc đặt mã nhận dạng bối cảnh để xác minh báo cáo sẽ giảm độ trễ này. Trong trường hợp này, có một độ trễ cố định, nhỏ hơn là 5 giây kể từ khi hoạt động SharedStorage bắt đầu.

Quy trình mẫu (như minh hoạ trong sơ đồ ở trên):

1. Thao tác Shared Storage được chạy bằng cấu hình Private Aggregation chỉ định một mã nhận dạng bối cảnh và một báo cáo có thể tổng hợp sẽ được tạo.
2. Mã nhận dạng bối cảnh được nhúng trong báo cáo tổng hợp đã tạo được gửi đến máy chủ của bạn.
3. Máy chủ của bạn thu thập các báo cáo tổng hợp đã tạo.
4. Các quy trình trên máy chủ của bạn sẽ kiểm tra mã nhận dạng bối cảnh trong từng báo cáo có thể tổng hợp dựa trên mã nhận dạng bối cảnh đã lưu trữ để xác minh tính hợp lệ của mã nhận dạng đó trước khi tạo hàng loạt báo cáo và gửi chúng đến Dịch vụ tổng hợp.

Xác minh mã nhận dạng bối cảnh

Bạn có thể xác minh các báo cáo đến máy chủ thu thập theo một số cách trước khi gửi đến Dịch vụ tổng hợp. Báo cáo có mã bối cảnh không hợp lệ có thể bị từ chối khi mã bối cảnh là:

• Không xác định: Nếu một báo cáo đến kèm theo mã bối cảnh mà hệ thống của bạn chưa tạo, bạn có thể loại bỏ báo cáo đó. Điều này giúp ngăn chặn các đối tượng xấu hoặc không xác định chèn dữ liệu vào quy trình tổng hợp của bạn.
• Bản sao: Nếu nhận được hai (hoặc nhiều) báo cáo có cùng mã nhận dạng bối cảnh, tức là bạn cần chọn báo cáo nào để loại bỏ.
• Bị gắn cờ trong quá trình phát hiện nội dung rác:
  • Nếu phát hiện thấy hoạt động đáng ngờ của một người dùng, chẳng hạn như hoạt động của người dùng đột ngột thay đổi, trong khi xử lý báo cáo của họ, bạn có thể loại bỏ báo cáo đó.
  • Bạn có thể lưu trữ báo cáo cùng với mã nhận dạng bối cảnh và mọi tín hiệu có liên quan (ví dụ: tác nhân người dùng, nguồn giới thiệu, v.v.). Sau đó, khi phân tích hành vi người dùng và xác định các chỉ báo mới về nội dung rác, bạn có thể đánh giá lại các báo cáo đã lưu trữ dựa trên mã nhận dạng bối cảnh và tín hiệu được liên kết. Nhờ đó, bạn có thể loại bỏ báo cáo của những người dùng có hoạt động đáng ngờ, ngay cả khi họ không bị gắn cờ ban đầu.

Tương tác và chia sẻ ý kiến phản hồi

Private Aggregation API đang được thảo luận tích cực 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 của bạn.

• GitHub: Đọc bài 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 trên kho lưu trữ Hỗ trợ nhà phát triển của Hộp cát về quyền riêng tư.
• Tham gia nhóm Shared Storage API và nhóm Protected Audience API để nhận thông báo mới nhất liên quan đến Private Aggregation.