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.
- Pengguna mengunjungi situs yang menampilkan iklan.
- 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()
. - 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.
- 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.
- Iklan pemenang ditampilkan sebagai nilai buram, yang ditampilkan dalam frame dengan fence. Penjual dan penayang tidak akan dapat melihat nilai ini.
- 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:
- Pengguna mengunjungi situs yang berpartisipasi.
- Lelang terprogram dijalankan oleh penjual lain guna menemukan iklan kontekstual untuk slot iklan yang tersedia.
- Lelang Protected Audience API berjalan.
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:
- 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.