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, 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

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 sẽ được gửi đến máy chủ của bạn để thu thập và phân lô. 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.

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 đều tạo ra các báo cáo tổng hợp mà phần phụ trợ của 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 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ính năng Tổng hợp riêng tư là một API dùng cho nhiều mục đích để đo lường trên nhiều trang web. Bạn có thể sử dụng tính năng này trong các công 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. 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. Để 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 trong độ tuổi từ 18 đến 45 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ư.

Mô hình phân bổ đa điểm

Hướng dẫn này được xuất bản trên trang web của nhà phát triển để các công nghệ quảng cáo có thể hiểu được cách triển khai MTA trong Bộ nhớ dùng chung + Tổng hợp riêng tư.

Với 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 đây có trong đối tượng privateAggregation có trong các công cụ trong Protected Audience API và Bộ nhớ dùng chung.

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 Private Aggregation API với mã nội dung được chuyển đổi thành khoá tổng hợp (bucket).

contributeToHistogramOnEvent()

Chỉ trong các công cụ trong 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 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ó 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 hướng dẫ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 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 tài liệu 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ư.