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 phiên đấu giá Protected Audience API.

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

Đọc hướng dẫn cho nhà phát triển để biết toàn bộ vòng đời của Protected Audience API và tham khảo phần giải thích về Protected Audience API để thảo luận chi tiết về báo cáo ở cấp sự kiện (tạm thời).

Bạn không phải là nhà phát triển? Hãy 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 chiến thắng, để tìm hiểu rằng họ đã thắng một 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 API tổng hợp riêng tư. Là một cơ chế báo cáo cấp sự kiện tạm thời, 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 kết quả đấu giá.

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

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

auctionConfig

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

browserSignals

Một đối tượng do trình duyệt tạo, 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ể bao gồm hàm reportWin() để báo cáo kết quả phiên đấu giá.

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

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

auctionSignals và perBuyerSignals

Các giá trị giống nhau được truyền đến generateBid() cho bên đặt giá thầu giành chiến thắng.

sellerSignals

Giá trị trả về của reportResult(), cho phép người bán có cơ hội truyền thông tin cho người mua.

browserSignals

Một đối tượng do trình duyệt tạo, 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 pháp 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 lấy một đối số duy nhất: một URL để tìm nạp sau khi phiên đấu giá hoàn tất. Các URL này có thể được gọi 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ất bại/thắng khi phiên đấu giá chạy đến khi hoàn tất. Nếu một phiên đấu giá bị huỷ (ví dụ: do một thao tác điều hướng mới), thì sẽ không có báo cáo nào được tạo.

Các phương thức này có sẵn theo mặc định trong Chrome nếu chrome://flags/#privacy-sandbox-ads-apis được bật. Tuy nhiên, nếu đang chạy Chrome có cờ dòng lệnh để bật Protected Audience API, thì bạn 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ờ không được bật, các phương thức sẽ vẫn còn nhưng không thực hiện tác vụ nào.

Tất cả tài liệu tham khảo về 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.

Tiếp theo là gì?

Chúng tôi muốn thảo luận với bạn để đảm bảo việc xây dựng một API phù hợp với tất cả mọi người.

Thảo luận về API

Giống như các API Hộp cát về quyền riêng tư khác, API này được ghi lại và thảo luận công khai.

Thử nghiệm với API

Bạn có thể thử nghiệm và tham gia cuộc trò chuyện về Protected Audience API.