Báo cáo về kết quả đấu giá Protected Audience API

Hướng dẫn dành cho người bán và người mua để tạo báo cáo đấu giá Protected Audience API.

Bài viết này là tài liệu tham khảo kỹ thuật để tạo báo cáo cho Phiên đấu giá sử dụng Protected Audience API thắng thầu, như cách sử dụng trong phiên bản thử nghiệm hiện tại Protected Audience API.

Đọc hướng dẫn cho nhà phát triển toàn bộ chu kỳ của Protected Audience API và tham khảo tài liệu giải thích về Protected Audience API để được thảo luận chuyên sâu về báo cáo ở cấp sự kiện (tạm thời).

Bạn không phải nhà phát triển? Tham khảo tổng quan về Protected Audience API.

Protected Audience API báo cáo nội dung gì?

Hiện có hai báo cáo Protected Audience API:

  • Báo cáo của người bán: Thông báo cho người bán về người chiến thắng trong phiên đấu giá quảng cáo.
  • Báo cáo người mua: Chỉ dành cho những người mua giành chiến thắng, để biết rằng họ đã thắng phiên đấu giá.

Kế hoạch dài hạn là để cho phép trình duyệt báo cáo kết quả phiên đấu giá cho người bán và người mua bằng API Tổng hợp riêng tư. Là một cơ chế báo cáo tạm thời ở cấp sự kiện, đoạn mã triển khai reportResult() cho người bán và reportWin() cho bên đặt giá thầu giành chiến thắng, có thể gọi hàm sendReportTo(). Phương thức này sẽ lấy một đối số duy nhất: một chuỗi đại diện cho một URL được tìm nạp sau khi phiên đấu giá hoàn tất, mã này mã hoá thông tin cấp sự kiện cần báo cáo.

Các hàm API

Người bán: reportResult()

JavaScript của người bán được cung cấp trong decisionLogicUrl (cũng cung cấp scoreAd()) có thể bao gồm hàm reportResult() để báo cáo phiên đấu giá kết quả.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Các đối số được truyền đến hàm này là:

auctionConfig

Đối tượng cấu hình phiên đấu giá được truyền đến navigator.runAdAuction().

browserSignals

Đối tượng được tạo bởi trình duyệt cung cấp thông tin về phiên đấu giá. Ví dụ:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

Giá trị trả về của hàm này được dùng làm đối số sellerSignals cho hàm reportWin() của bên đặt giá thầu giành chiến thắng.

Người mua: reportWin()

JavaScript của bên đặt giá thầu giành chiến thắng (cũng cung cấp generateBid()) có thể thêm một hàm reportWin() để báo cáo kết quả phiên đấu giá.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Các đối số được truyền đến hàm này là:

auctionSignals và perBuyerSignals

Các giá trị tương tự đã được chuyển đến generateBid() cho chiến thắng bên đặt giá thầu.

sellerSignals

Giá trị trả về của reportResult(), đem lại cho người bán cơ hội truyền thông tin đến người mua.

browserSignals

Đối tượng được tạo bởi trình duyệt cung cấp thông tin về phiên đấu giá. Ví dụ:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Triển khai báo cáo tạm thời

Có hai phương thức tạm thời có sẵn trong Chrome để báo cáo phiên đấu giá:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Mỗi phương thức này sẽ nhận một đối số duy nhất: một URL để tìm nạp sau phiên đấu giá đã hoàn tất. Bạn có thể gọi các hàm này nhiều lần, trong cả scoreAd() và generateBid(), với các đối số URL khác nhau.

Chrome chỉ gửi báo cáo gỡ lỗi/thắng/thua khi phiên đấu giá kết thúc. Nếu một phiên đấu giá bị huỷ (ví dụ: do điều hướng mới) sẽ không có báo cáo nào được tạo.

Những phương thức này có sẵn trong Chrome theo mặc định khi bạn bật tất cả các API Quyền riêng tư trong quảng cáo trong chrome://settings/adPrivacy. Nếu bạn đang chạy Chrome có cờ hiệu dòng lệnh để bật Protected Audience API, bạn sẽ cần bật các phương thức một cách rõ ràng bằng cách thêm cờ BiddingAndScoringDebugReportingAPI. Nếu cờ này không được bật, các phương thức sẽ vẫn có sẵn nhưng không làm gì cả.

Tất cả tệp tham chiếu đến Protected Audience API

Hướng dẫn tham khảo API có sẵn:

Thông tin giải thích về Protected Audience API cũng cung cấp thông tin chi tiết về các quy tắc hỗ trợ và các quy tắc ràng buộc của tính năng.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.