Laporan hasil lelang Protected Audience API

Panduan penjual dan pembeli untuk membuat laporan lelang Protected Audience API.

Artikel ini adalah referensi teknis untuk membuat laporan tentang Lelang Protected Audience API menang, seperti yang digunakan dalam iterasi eksperimen saat ini Protected Audience API.

Baca panduan developer untuk selengkapnya siklus Protected Audience API, dan membaca penjelasan Protected Audience API untuk mengetahui diskusi mendalam tentang pelaporan tingkat peristiwa (sementara).

Bukan developer? Lihat ringkasan Protected Audience API API.

Apa yang dilaporkan oleh Protected Audience API?

Ada dua laporan Protected Audience API yang tersedia:

  • Laporan penjual: Memberi tahu penjual tentang pemenang lelang iklan.
  • Laporan pembeli: Tersedia hanya bagi pembeli yang menang, untuk mengetahui bahwa mereka telah memenangkan lelang.

Rencana jangka panjangnya adalah memungkinkan browser melaporkan hasil lelang untuk penjual dan pembeli dengan Private Aggregation API. Sebagai mekanisme pelaporan tingkat peristiwa sementara, kode yang menerapkan reportResult() untuk penjual, dan reportWin() untuk bidder yang menang, dapat panggil fungsi sendReportTo(). Ini membutuhkan satu argumen: string mewakili URL yang diambil setelah lelang selesai, yang mengenkode informasi tingkat peristiwa yang akan dilaporkan.

Fungsi API

Penjual: reportResult()

JavaScript penjual yang disediakan di decisionLogicUrl (yang juga menyediakan scoreAd()) dapat menyertakan fungsi reportResult(), untuk melaporkan lelang hasil proyek.

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

Argumen yang diteruskan ke fungsi ini adalah:

auctionConfig

Objek konfigurasi lelang yang diteruskan ke navigator.runAdAuction().

browserSignals

Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Contoh:

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

Nilai hasil dari fungsi ini digunakan sebagai argumen sellerSignals untuk fungsi reportWin() bidder yang menang.

Pembeli: reportWin()

JavaScript bidder yang menang (yang juga menyediakan generateBid()) dapat menyertakan fungsi reportWin() untuk melaporkan hasil lelang.

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

Argumen yang diteruskan ke fungsi ini adalah:

auctionSignals dan perBuyerSignals

Nilai yang sama diteruskan ke generateBid() untuk pemenang menjadi bidder.

sellerSignals

Nilai hasil reportResult(), yang memberi penjual untuk meneruskan informasi kepada pembeli.

browserSignals

Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Contoh:

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

Penerapan pelaporan sementara

Ada dua metode yang tersedia sementara di Chrome untuk pelaporan lelang:

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

Masing-masing metode ini mengambil satu argumen: URL yang akan diambil setelah lelang selesai. Metode ini dapat dipanggil beberapa kali, dalam scoreAd() dan generateBid(), dengan argumen URL berbeda.

Chrome hanya mengirim laporan kekalahan/kemenangan debug saat lelang berjalan hingga selesai. Jika lelang dibatalkan (misalnya, karena navigasi baru), tidak ada laporan dibuat.

Metode ini tersedia secara default di Chrome saat Anda mengaktifkan semua API privasi iklan di chrome://settings/adPrivacy. Jika Anda menjalankan Chrome dengan tanda command line untuk mengaktifkan Protected Audience API, Anda harus mengaktifkan metode tersebut secara eksplisit dengan menyertakan tanda BiddingAndScoringDebugReportingAPI. Jika flag tidak diaktifkan, metode akan tetap tersedia, tetapi tidak melakukan apa pun.

Semua referensi Protected Audience API API

Panduan referensi API tersedia:

Penjelasan Protected Audience API juga memberikan detail tentang dukungan dan batasan fitur.

后续操作

我们希望与您交流，确保我们构建适合所有人的 API。

讨论 API

与其他 Privacy Sandbox API 一样，此 API 也会记录在案并公开讨论。

使用 API 进行实验

您可以进行实验并参与有关 Protected Audience API 的对话。