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.

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.