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 saat ini dari Protected Audience API eksperimental.

Baca panduan developer untuk selengkapnya siklus Protected Audience API, dan membaca 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 browser berjalan di perangkat pengguna untuk memilih iklan. Untuk menjaga privasi, semua iklan kode lelang dari penjual dan pembeli dijalankan di JavaScript yang terisolasi worklet yang tidak dapat berkomunikasi dengan dunia luar.

1. Pengguna mengunjungi situs yang menampilkan iklan.
2. Kode penjual mengeksekusi navigator.runAdAuction(). Ini menentukan ruang iklan dijual dan siapa yang dapat mengajukan bid. Penjual juga harus menyertakan skrip yang mencetak skor setiap bid, scoreAd().
3. Kode pembeli yang diundang dieksekusi untuk menghasilkan bid, URL untuk iklan yang relevan materi iklan, dan data lainnya. Skrip bidding dapat mengkueri data real-time, seperti sisa anggaran kampanye iklan, dari Layanan Kunci/Nilai.
4. Kode penjual menilai setiap bid dan memilih pemenang. Logika ini menggunakan metode nilai bid dan data lainnya menghasilkan bid yang diinginkan. Iklan yang tidak dapat dikalahkan pemenang kontekstual ditolak. Penjual dapat menggunakan Layanan Kunci/Nilai untuk data real-time.
5. Iklan pemenang ditampilkan sebagai nilai buram, yang ditampilkan dalam frame dengan fence. Baik penjual maupun penayang tidak akan dapat melihat nilai ini.
6. Lelang dilaporkan kepada penjual dan pembeli yang menang.

Kapan lelang berlangsung?

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

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 dijalankan.
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 secara mandiri untuk menghosting konten iklan di situsnya.
• Platform sisi suplai (SSP): bekerja sama dengan penayang dan menyediakan layanan lainnya.
• Skrip pihak ketiga: bertindak untuk penayang, untuk mengaktifkan partisipasi dalam lelang iklan.

Dengan Protected Audience API, penjual memiliki tiga tugas:

• Terapkan aturan penayang: pembeli mana dan bid mana yang valid.
• 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 memicu 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. Nilai 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 individual, beserta bid dan metadata yang terkait, satu per satu, lalu menetapkan skor keinginan.

auctionConfig properti

seller

Wajib diisi

Contoh: 'https://ssp.example'

Peran: Asal penjual.

decisionLogicUrl

Wajib diisi

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 diisi

Contoh: ['https://dsp.example', 'https://buyer2.example', ...]

Peran: Asal semua pemilik grup minat yang diminta untuk mengajukan bid dalam lelang.

Catatan: Penjual dapat menentukan interestGroupBuyers: untuk mengizinkan semua grup minat 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, pembuatan permintaan iklan kontekstual, dll.

sellerTimeout

Opsional

Contoh: 100

Peran: Runtime maksimum (md) 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) 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, diteruskan ke runAdAuction(). URL ini harus berisi skrip untuk Fungsi scoreAd(). Logika ini dijalankan satu kali untuk setiap iklan 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 mana yang mungkin ingin verifikasi:

{
  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:

Pertanyaan umum (FAQ)

Bagaimana pemenang lelang ditentukan dan siapa yang akan memilihnya?

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

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

Semua referensi Protected Audience API

Panduan referensi API tersedia:

• Panduan developer untuk Protected Audience API.
• Panduan pembeli iklan untuk grup minat dan pembuatan bid Protected Audience.
• Panduan penjual iklan untuk lelang iklan Protected Audience.
• Panduan melaporkan hasil lelang
• Praktik terbaik untuk latensi lelang iklan Protected Audience
• Memecahkan Masalah Protected Audience

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