Menjalankan lelang berbasis browser dengan satu penjual

Dalam dokumen ini, Anda akan menemukan ringkasan umum 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 penjual tunggal disebut sebagai "lelang komponen", yang dapat menyediakan kandidat iklan ke "lelang tingkat teratas" yang memiliki beberapa penjual yang berpartisipasi.

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

Enam tahap lelang iklan Protected Audience API

Enam tahap dalam lelang iklan Protected Audience API
Diagram ini menguraikan setiap tahap lelang iklan Protected Audience API.
  1. Pengguna mengunjungi situs yang menampilkan iklan.
  2. Kode penjual mengeksekusi navigator.runAdAuction(). Kolom ini menentukan ruang iklan mana yang akan dijual dan siapa yang dapat mengajukan bid. Penjual juga harus menyertakan skrip yang menilai setiap bid, scoreAd().
  3. Kode pembeli yang diundang dijalankan untuk membuat bid, URL untuk materi iklan yang relevan, dan data lainnya. Skrip bidding dapat mengkueri data real-time, seperti sisa anggaran kampanye iklan, dari layanan Kunci/Nilai pembeli.
  4. Kode penjual memberi skor untuk setiap bid dan memilih pemenang. Logika ini menggunakan nilai bid dan data lainnya menampilkan nilai bid yang diinginkan. Iklan yang tidak dapat mengalahkan pemenang kontekstual akan ditolak. Penjual dapat menggunakan layanan Kunci/Nilai sendiri untuk data real-time.
  5. Iklan pemenang ditampilkan sebagai nilai buram, yang ditampilkan dalam frame dengan fence. 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 muncul.

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

Penjual dapat merujuk ke:

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

Prasyarat untuk menjalankan lelang

Penjual memerlukan dua fungsi JavaScript yang ditentukan untuk menjalankan lelang:

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

Skrip ini harus ditayangkan dari endpoint tunggal yang dimiliki penjual.

scoreAd()

Penjual harus menentukan fungsi scoreAd() yang disalurkan dari endpoint miliknya. Endpoint ditetapkan 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 harus ditentukan dan disetujui oleh penjual dan pembeli terkait strukturnya.
  • 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 skrip lelang penjual yang mungkin ingin diverifikasi.
  • directFromSellerSignals adalah objek yang mungkin 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 yang ia miliki. Endpoint ditetapkan 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 skrip lelang penjual yang mungkin ingin diverifikasi. 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 yang dapat diberikan penjual tentang lelang yang diperlukan pembeli untuk pelaporannya.

Menjalankan lelang Protected Audience API

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

  1. Konfigurasikan lelang. Langkah ini mencakup pembuatan objek auctionConfig. Hal ini memungkinkan penjual untuk menentukan pembeli mana yang harus berpartisipasi dalam lelang, serta memberikan sinyal yang mungkin relevan selama pembuatan bid atau penskoran iklan.
  2. Jalankan lelang dengan memanggil navigator.runAdAuction(), yang meneruskan konfigurasi yang dibuat pada langkah sebelumnya. Tindakan ini akan memulai rantai pembeli yang membuat bid, kemudian memberi skor. Hasil akhir dari langkah ini adalah kandidat iklan yang dapat dirender untuk menampilkan iklan.
  3. Render iklan pemenang dalam frame atau iframe dengan fence.
  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. Opsi ini menggunakan reportResult() penjual yang dijelaskan sebelumnya dalam panduan ini untuk melaporkan ke server mereka.