Laporan hasil lelang Protected Audience API

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

Artikel ini merupakan referensi teknis untuk membuat laporan pemenang lelang Protected Audience API, seperti yang digunakan dalam iterasi eksperimental Protected Audience API eksperimental saat ini.

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

Bukan developer? Lihat ringkasan Protected Audience 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: Hanya tersedia bagi pembeli yang menang, untuk mempelajari bahwa mereka telah memenangkan lelang.

Rencana jangka panjangnya adalah memungkinkan browser melaporkan hasil lelang untuk penjual dan pembeli dengan Private Aggregation API API. Sebagai mekanisme pelaporan tingkat peristiwa sementara, kode yang menerapkan reportResult() untuk penjual, dan reportWin() untuk bidder pemenang, dapat memanggil fungsi sendReportTo(). Tindakan ini memerlukan satu argumen: string yang 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 hasil lelang.

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

Argumen yang diteruskan ke fungsi ini adalah:

auctionConfig

Objek konfigurasi lelang diteruskan ke navigator.runAdAuction().

browserSignals

Objek yang dibuat oleh browser yang menyediakan 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 pemenang (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 bidder pemenang.

sellerSignals

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

browserSignals

Objek yang dibuat oleh browser yang menyediakan 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>
}

Implementasi 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. Fungsi ini dapat dipanggil beberapa kali, baik di scoreAd() maupun generateBid(), dengan argumen URL yang berbeda.

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

Metode ini tersedia secara default di Chrome jika chrome://flags/#privacy-sandbox-ads-apis diaktifkan. Namun, jika menjalankan Chrome dengan tanda command line untuk mengaktifkan Protected Audience API, Anda harus mengaktifkan metode secara eksplisit dengan menyertakan tanda BiddingAndScoringDebugReportingAPI. Jika tanda ini tidak diaktifkan, metode akan tetap tersedia, tetapi tidak melakukan apa pun.

Semua referensi Protected Audience API

Panduan referensi API tersedia:

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

Apa selanjutnya?

Kami ingin berbincang dengan Anda untuk memastikan bahwa kami membangun API yang berlaku untuk semua orang.

Diskusikan API

Seperti API Privacy Sandbox lainnya, API ini didokumentasikan dan dibahas secara publik.

Bereksperimen dengan API

Anda dapat bereksperimen dan berpartisipasi dalam percakapan tentang Protected Audience API.