Menjalankan lelang berbasis browser dengan satu penjual

Dalam dokumen ini, Anda akan menemukan ringkasan tingkat tinggi untuk menjalankan lelang dengan data Protected Audience untuk satu penjual, seperti yang digunakan dalam iterasi Protected Audience API saat ini. Lelang dengan satu penjual dapat dieksekusi sebagai bagian dari lelang yang lebih kompleks yang melibatkan beberapa penjual. Dalam hal ini, lelang penjual tunggal disebut sebagai "lelang komponen", yang dapat menyediakan kandidat iklan ke "lelang tingkat teratas" yang diikuti oleh beberapa penjual.

Baca panduan developer untuk siklus proses lengkap Protected Audience API, dan lihat penjelasan Protected Audience API untuk pembahasan mendalam tentang cara penjual menjalankan lelang di perangkat.

Enam tahap lelang iklan Protected Audience API

1. Pengguna mengunjungi situs yang menampilkan iklan.
2. Kode penjual menjalankan navigator.runAdAuction(). Bagian ini menentukan ruang iklan yang dijual dan siapa yang dapat mengajukan bid. Penjual juga harus menyertakan skrip yang memberi skor pada setiap bid, scoreAd().
3. Kode pembeli yang diundang dijalankan untuk membuat bid, URL untuk materi iklan yang relevan, dan data lainnya. Skrip bidding dapat membuat kueri untuk data real-time, seperti sisa anggaran kampanye iklan, dari layanan Nilai/Kunci pembeli.
4. Kode penjual memberi skor pada setiap bid dan memilih pemenang. Logika ini menggunakan nilai bid dan data lain untuk menampilkan daya tarik bid. Iklan yang tidak dapat mengalahkan pemenang kontekstual akan ditolak. Penjual dapat menggunakan layanan Kunci/Nilai mereka sendiri untuk data real-time.
5. Iklan pemenang ditampilkan sebagai nilai buram, yang ditampilkan dalam frame tertutup. Penjual dan penayang tidak akan dapat melihat nilai ini.
6. Lelang dilaporkan kepada penjual dan pembeli yang menang.

Lelang dapat berlangsung saat pengguna membuka halaman yang menampilkan iklan. Lelang dapat dijalankan lebih awal sehingga materi iklan siap saat slot iklan terlihat.

Penjual memulai lelang iklan, menilai iklan kandidat menggunakan logika kustom yang diberikan sebagai fungsi scoreAd(), dan bertanggung jawab untuk melaporkan hasil lelang kepada diri mereka sendiri serta pembeli pemenang. Penjual juga dapat menerapkan aturan penayang dan memfilter kualitas iklan menggunakan fungsi scoreAd() mereka.

Penjual dapat merujuk pada:

• Penerbit konten, yang bertindak untuk dirinya sendiri dalam menghosting konten iklan di situsnya
• Platform sisi suplai (SSP), yang bekerja sama dengan penayang iklan dan menyediakan layanan lainnya
• Skrip pihak ketiga, yang bertindak untuk penayang agar dapat berpartisipasi dalam lelang iklan.

Prasyarat untuk menjalankan lelang

Penjual memerlukan dua fungsi JavaScript yang ditentukan untuk menjalankan lelang:

• scoreAd(), yang memberi skor pada kandidat iklan
• reportResult(), yang menangani pelaporan hasil lelang kepada penjual itu sendiri

Skrip ini harus ditayangkan dari satu endpoint yang dimiliki penjual.

scoreAd()

Penjual harus menentukan fungsi scoreAd() yang ditayangkan dari endpoint miliknya. Endpoint ditentukan dalam konfigurasi lelang sebagai decisionLogicUrl. Fungsi scoreAd() memiliki tanda tangan berikut:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Parameter scoreAd() adalah:

• adMetaData, yang merupakan metadata arbitrer tentang materi iklan yang disediakan oleh pembeli. Ini adalah objek yang dapat diserialisasi JSON yang struktur dan definisinya harus ditentukan dan disepakati oleh penjual dan pembeli.
• bid, yang merupakan nilai numerik yang mewakili bid.
• auctionConfig, yang merupakan konfigurasi lelang yang digunakan untuk menjalankan lelang.
• trustedScoringSignals, yang merupakan sinyal yang dibaca pada waktu lelang dari server Key/Value penjual. Platform akan menggunakan renderUrl iklan kandidat sebagai kunci untuk pencarian ini.
• browserSignals, yang merupakan objek yang dibuat oleh browser, termasuk informasi yang diketahui browser dan yang mungkin ingin diverifikasi oleh skrip lelang penjual.
• directFromSellerSignals adalah objek yang dapat berisi kolom berikut: ** sellerSignals: Seperti auctionConfig.sellerSignals, tetapi diteruskan menggunakan mekanisme directFromSellerSignals. ** auctionSignals: Seperti auctionConfig.auctionSignals, tetapi diteruskan menggunakan mekanisme directFromSellerSignals.

Berikut adalah contoh browserSignals. Perhatikan bahwa renderUrl iklan kandidat tersedia melalui sinyal berikut:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Penjual harus menentukan fungsi reportResult() yang ditayangkan dari endpoint miliknya. Endpoint ditentukan dalam konfigurasi lelang sebagai decisionLogicUrl. Fungsi reportResult() memiliki tanda tangan berikut:

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

Parameter reportResult() adalah:

• auctionConfig, yang merupakan konfigurasi lelang yang digunakan untuk menjalankan lelang.
• browserSignals, yang merupakan objek yang dibuat oleh browser, termasuk informasi yang diketahui browser dan yang mungkin ingin diverifikasi oleh skrip lelang penjual. Ini adalah objek yang sama yang diteruskan ke fungsi scoreAds().

reportResult() menampilkan signalsForWinner, yang merupakan objek JSON arbitrer yang diteruskan ke fungsi pelaporan pembeli yang menang. Hal ini harus mencakup informasi relevan apa pun yang dapat diberikan penjual tentang lelang yang diperlukan pembeli untuk pelaporan mereka.

Menjalankan lelang Protected Audience API

Ada empat langkah utama yang harus dilakukan penjual untuk menjalankan lelang. Perhatikan bahwa langkah-langkah ini mengasumsikan penjual telah menyiapkan endpoint untuk menampilkan JavaScript yang diperlukan yang disebutkan sebelumnya dalam panduan ini.

1. Konfigurasi lelang. Langkah ini mencakup pembuatan objek auctionConfig. Hal ini memungkinkan penjual menentukan pembeli mana yang harus berpartisipasi dalam lelang, serta memberikan sinyal yang mungkin relevan selama pembuatan bid atau pemberian skor iklan.
2. Jalankan lelang dengan memanggil navigator.runAdAuction(), dengan meneruskan konfigurasi yang dibuat pada langkah sebelumnya. Tindakan ini memulai rangkaian pembeli yang membuat bid, lalu memberikan skor. Hasil akhir langkah ini adalah kandidat iklan yang dapat dirender untuk menampilkan iklan.
3. Merender iklan pemenang dalam frame tertutup atau iframe.
4. Laporkan hasil lelang. Ada fungsi, navigator.sendReportTo(), yang akan memulai pelaporan. Penjual akan selalu menerima laporan hasil lelang. Hanya pembeli yang memenangkan lelang yang akan menerima laporan. Hal ini menggunakan reportResult() penjual yang dijelaskan sebelumnya dalam panduan ini untuk melaporkan ke server mereka.