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, sebagaimana digunakan dalam iterasi saat ini dari Protected Audience API eksperimental.

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.

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 di worklet JavaScript terisolasi yang tidak dapat berkomunikasi dengan dunia luar.

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.

Kapan lelang berlangsung?

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

1. Pengguna mengunjungi situs yang berpartisipasi.
2. Lelang terprogram dijalankan oleh penjual lain untuk 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 dapat menjalankan lelang untuk menjual ruang iklan.

Contoh:

• Penayang konten: bertindak untuk dirinya sendiri dalam 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:

• Menerapkan aturan penayang: pembeli dan bid mana yang memenuhi syarat.
• Menjalankan logika lelang: JavaScript dijalankan di worklet untuk menghitung skor keinginan untuk setiap bid.
• Laporkan hasil lelang.

Tugas ini dilakukan secara terprogram, dalam kode yang disediakan oleh penjual saat penjual memulai 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 merepresentasikan hasil lelang iklan. Ini hanya dapat didekode oleh browser saat diteruskan ke frame tertutup untuk rendering: halaman penayang tidak dapat memeriksa iklan yang menang.

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

Properti auctionConfig

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'

Role: 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 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 mengonfirmasi kepatuhan terhadap kebijakan mereka.

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: Waktu proses 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: Waktu proses maksimum (ms) 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 daya tariknya.

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

browserSignals

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

{
  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 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 memilihnya?

Penjual memberikan logika pemberian skor untuk menentukan skor keinginan setiap iklan, dan browser memilih skor tertinggi sebagai iklan pemenang.

Penjual menyertakan logika dalam fungsi scoreAd(), dan browser menjalankan fungsi dalam worklet yang memiliki komunikasi terbatas dengan kode di luarnya. Browser itu sendiri tidak memberi skor pada iklan. Browser bertanggung jawab secara eksklusif untuk menjalankan logika pemberian skor 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.