Panduan penjual: menjalankan lelang iklan

Panduan dan referensi API penjual untuk lelang iklan Protected Audience API.

Dalam artikel ini, Anda akan menemukan referensi teknis untuk lelang iklan, seperti yang digunakan dalam iterasi Protected Audience API eksperimental saat ini.

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.

Bukan developer? Lihat Ringkasan Protected Audience API.

Apa yang dimaksud dengan lelang iklan Protected Audience API?

Lelang iklan Protected Audience API adalah kumpulan program JavaScript kecil yang dijalankan browser di perangkat pengguna untuk memilih iklan. Untuk menjaga privasi, semua kode lelang iklan dari penjual dan pembeli dijalankan dalam worklet JavaScript terpisah yang tidak dapat berkomunikasi dengan dunia luar.

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.

Kapan lelang berlangsung?

Protected Audience API dapat berjalan sendiri atau dengan lelang terprogram. Dalam lelang terprogram multi-penjual:

  1. Pengguna mengunjungi situs yang berpartisipasi.
  2. Lelang terprogram dijalankan oleh penjual lain guna menemukan iklan kontekstual untuk slot iklan yang tersedia.
  3. Lelang Protected Audience API berjalan.
  4. scoreAd()membandingkan bid pembeli dengan hasil lelang pertama.

Bid yang tidak dapat mengalahkan pemenang kontekstual akan ditolak.

Siapa yang menjalankan lelang iklan Protected Audience API?

Ada beberapa pihak yang mungkin menjalankan lelang untuk menjual ruang iklan.

Contoh:

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

Dengan Protected Audience API, penjual memiliki tiga pekerjaan:

  • Terapkan aturan penayang: pembeli dan bid mana yang memenuhi syarat.
  • Jalankan logika lelang: JavaScript berjalan di worklet untuk menghitung skor keinginan untuk setiap bid.
  • Melaporkan hasil lelang.

Tugas ini dilakukan secara terprogram, dalam kode yang disediakan oleh penjual saat menghasut lelang iklan dengan memanggil fungsi JavaScript navigator.runAdAuction().

Fungsi API

runAdAuction()

Penjual membuat permintaan ke browser pengguna untuk memulai lelang iklan dengan memanggil navigator.runAdAuction().

Contoh:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() menampilkan promise yang di-resolve ke URN (urn:uuid:<something>) yang mewakili hasil lelang iklan. Kunci ini hanya dapat didekode oleh browser saat diteruskan ke frame dengan fence untuk rendering: halaman penayang tidak dapat memeriksa iklan pemenang.

Skrip decisionLogicUrl mempertimbangkan setiap iklan, beserta bid dan metadata terkaitnya, satu per satu, lalu menetapkan skor keinginan numerik padanya.

auctionConfig properti

seller
Wajib
Contoh: 'https://ssp.example'
Peran: Asal penjual.
decisionLogicUrl
Wajib
Contoh: 'https://ssp.example/auction-decision-logic.js'
Peran: URL untuk JavaScript worklet lelang.
trustedScoringSignalsUrl
Opsional
Contoh: 'https://ssp.example/scoring-signals'
Peran: URL server tepercaya penjual.
interestGroupBuyers
Wajib
Contoh: ['https://dsp.example', 'https://buyer2.example', ...]
Peran: Asal semua pemilik grup minat yang diminta untuk mengajukan bid dalam lelang.
Catatan: Penjual dapat menetapkan interestGroupBuyers: untuk mengizinkan semua grup minat untuk mengajukan bid. Iklan kemudian diterima atau ditolak berdasarkan kriteria selain penyertaan pemilik grup minat. Misalnya, penjual dapat meninjau materi iklan untuk memastikan kepatuhannya terhadap kebijakannya.
auctionSignals
Opsional
Contoh: {...}
Peran: Informasi penjual tentang konteks halaman, jenis lelang, dll.
sellerSignals
Opsional
Contoh: {...}
Peran: Informasi berdasarkan setelan penayang, membuat permintaan iklan kontekstual, dll.
sellerTimeout
Opsional
Contoh: 100
Peran: Runtime maksimum (md) dari skrip scoreAd() penjual.
perBuyerSignals
Opsional
Contoh: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Peran: Sinyal kontekstual tentang halaman untuk setiap pembeli tertentu, dari server mereka.
perBuyerTimeouts
Opsional
Contoh: 50
Peran: Runtime maksimum (md) dari skrip generateBid() pembeli tertentu.
componentAuctions
Opsional
Contoh: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Peran: Konfigurasi tambahan untuk lelang komponen.

decisionLogicUrl

decisionLogicUrl adalah properti objek konfigurasi lelang, yang diteruskan ke runAdAuction(). URL ini harus menyertakan skrip untuk fungsi scoreAd(). Logika ini dijalankan sekali untuk setiap iklan guna menentukan keinginannya.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals adalah objek yang dibuat oleh browser, termasuk informasi yang diketahui browser dan skrip lelang penjual yang mungkin ingin diverifikasi:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

Sebelum lelang dimulai, penjual menemukan iklan kontekstual terbaik untuk slot iklan yang tersedia. Bagian dari logika scoreAd() menolak iklan apa pun yang tidak dapat mengalahkan pemenang kontekstual.

scoreAd()

scoreAd() menggunakan argumen berikut:

Argumen Role
adMetadata Metadata arbitrer disediakan oleh pembeli.
auctionConfig Objek konfigurasi lelang diteruskan ke navigator.runAdAuction().
bid Nilai bid numerik.
trustedScoringSignals Nilai yang diambil pada waktu lelang dari server tepercaya penjual, yang menunjukkan pendapat penjual tentang iklan tersebut.

Pertanyaan umum (FAQ)

Bagaimana pemenang lelang ditentukan dan siapa yang memilihnya?

Penjual menyediakan logika penskoran untuk menentukan skor yang diinginkan untuk setiap iklan, dan browser memilih skor tertinggi sebagai iklan pemenang.

Penjual menyertakan logika dalam fungsi scoreAd(), dan browser menjalankan fungsi di worklet yang memiliki komunikasi terbatas dengan kode di luarnya. Browser itu sendiri tidak menilai iklan. Browser secara eksklusif bertanggung jawab untuk menjalankan logika penskoran dan memilih bid dengan skor tertinggi.

Semua referensi Protected Audience API

Panduan referensi API tersedia:

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