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.
- Pengguna mengunjungi situs yang menampilkan iklan.
- 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()
. - 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.
- 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.
- Iklan pemenang ditampilkan sebagai nilai buram, yang ditampilkan dalam frame dengan fence. Baik penjual maupun penayang tidak akan dapat melihat nilai ini.
- 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:
- Pengguna mengunjungi situs yang berpartisipasi.
- Lelang terprogram dijalankan oleh penjual lain guna menemukan iklan kontekstual untuk slot iklan yang tersedia.
- Lelang Protected Audience API dijalankan.
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:
Argumen | Peran |
---|---|
adMetadata |
Metadata arbitrer yang disediakan oleh pembeli. |
auctionConfig |
Objek konfigurasi lelang yang diteruskan ke navigator.runAdAuction() . |
bid |
Nilai bid numerik. |
trustedScoringSignals |
Nilai yang diambil pada waktu lelang dari server tepercaya penjual, yang mewakili opini penjual tentang iklan. |
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
以下是 API 参考指南:
- Protected Audience API 开发者指南。
- 有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
- Protected Audience 广告竞价广告卖方指南。
- 关于报告竞价结果的指南
- Protected Audience 广告竞价延迟时间方面的最佳实践
- 对 Protected Audience 进行问题排查
Protected Audience API 说明信息还详细介绍了功能支持和限制条件。