Menjalankan lelang berbasis browser dengan satu penjual

bookmark_border Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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 dijalankan sebagai bagian dari lelang yang lebih kompleks yang melibatkan beberapa penjual. Dalam hal ini, lelang satu penjual 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 diskusi 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 mengeksekusi navigator.runAdAuction(). Ini menentukan ruang iklan yang dijual dan siapa yang dapat mengajukan bid. Penjual juga harus menyertakan skrip yang memberi skor setiap bid, scoreAd().
3. Kode pembeli yang diundang akan dijalankan untuk menghasilkan 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 lainnya yang menampilkan keinginan 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 bingkai berpagar. Penjual dan penayang tidak akan dapat melihat nilai ini.
6. Lelang dilaporkan kepada penjual dan pembeli yang menang.

Lelang dapat terjadi 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 disediakan sebagai fungsi scoreAd(), dan bertanggung jawab 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 ke:

• Penayang konten, yang bertindak untuk dirinya sendiri guna 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 guna memungkinkan partisipasi dalam lelang iklan.

Prasyarat untuk menjalankan lelang

Penjual memerlukan dua fungsi JavaScript yang ditentukan untuk menjalankan lelang:

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

Skrip ini harus ditayangkan dari satu endpoint yang dimiliki penjual.

scoreAd()

Penjual perlu menentukan fungsi scoreAd() yang ditayangkan dari endpoint yang mereka miliki. 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 JSON yang dapat diserialisasi yang harus ditentukan dan disetujui 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 Kunci/Nilai 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 ini:

{ '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 perlu menentukan fungsi reportResult() yang ditayangkan dari endpoint yang mereka miliki. 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 pemenang. Laporan 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 memiliki endpoint yang disiapkan untuk menampilkan JavaScript yang diperlukan yang sebelumnya disebutkan dalam panduan ini.

1. Konfigurasikan lelang. Langkah ini mencakup pembuatan objek auctionConfig. Hal ini memungkinkan penjual menentukan pembeli mana yang harus berpartisipasi dalam lelang, serta memberikan sinyal apa pun yang mungkin relevan selama pembuatan bid atau penskoran iklan.
2. Jalankan lelang dengan memanggil navigator.runAdAuction(), dengan meneruskan konfigurasi yang dibuat pada langkah sebelumnya. Tindakan ini akan memulai rantai pembeli yang menghasilkan bid, lalu penskoran. Hasil akhir dari langkah ini adalah kandidat iklan yang dapat dirender untuk menampilkan iklan.
3. Render iklan pemenang dalam bingkai atau iframe berpagar.
4. Melaporkan hasil lelang. Ada fungsi, navigator.sendReportTo(), yang akan memulai pelaporan. Penjual akan selalu menerima laporan hasil lelang. Hanya pembeli yang telah memenangkan lelang yang akan menerima laporan. Hal ini menggunakan reportResult() penjual yang dijelaskan sebelumnya dalam panduan ini untuk melaporkan ke server mereka.