Pelajari cara mengonfigurasi lelang Protected Audience API.
Lelang di perangkat yang dijalankan oleh penjual
Lelang Protected Audience di perangkat berjalan di situs yang menjual ruang iklan, dan kami menganggap pihak yang menjalankan lelang sebagai penjual. Banyak pihak dapat bertindak sebagai penjual: situs dapat menjalankan lelang iklannya sendiri, atau mungkin menyertakan skrip pihak ketiga untuk menjalankan lelang untuk situs tersebut, atau mungkin menggunakan SSP yang menggabungkan proses menjalankan lelang di perangkat dengan aktivitas lelang iklan sisi server lainnya. Penjual memiliki tiga tugas dasar dalam lelang iklan di perangkat:
- Penjual menentukan (a) pembeli mana yang dapat berpartisipasi, dan (b) bid mana dari grup minat pembeli tersebut yang memenuhi syarat untuk mengikuti lelang. Dengan begitu, penjual dapat menerapkan aturan situs terkait iklan yang diizinkan untuk muncul di halaman.
- Penjual bertanggung jawab atas logika bisnis lelang: kode JavaScript yang mempertimbangkan harga dan metadata setiap bid, serta menghitung skor "keinginan". Bid dengan skor keinginan tertinggi akan memenangkan lelang.
- Penjual melakukan pelaporan hasil lelang, termasuk informasi tentang pemesanan harga dan pembayaran lainnya. Pembeli yang menang dan kalah juga dapat melakukan pelaporan mereka sendiri.
Dokumen ini akan menjelaskan cara mengonfigurasi dan memulai lelang di perangkat.
Mengonfigurasi lelang iklan Protected Audience API
Untuk menjalankan lelang iklan Protected Audience API, langkah pertama adalah
mengonfigurasi lelang. Hal ini dilakukan dengan membuat objek auctionConfig
.
Berikut adalah contoh dari salah satu konfigurasi tersebut:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig
properti
Properti wajib
Satu-satunya properti yang diperlukan untuk auctionConfigs
adalah seller
,
decisionLogicUrl
, dan interestGroupBuyers
.
Properti | Contoh | Role |
---|---|---|
seller | https://seller.example | Asal penjual. |
decisionLogicUrl | https://seller.example/decision-logic.js | URL untuk worklet logika keputusan JavaScript lelang. Kolom ini harus memiliki asal yang sama dengan kolom penjual. |
interestGroupBuyers | [https://pembeli-1.contoh, https://pembeli-2.contoh, ...] |
Asal semua pemilik grup minat yang diminta untuk melakukan bidding dalam lelang |
Properti opsional
Properti lainnya untuk auctionConfigs
bersifat opsional.
Properti | Contoh | Role |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL server Kunci/Nilai penjual. Hal ini akan dikueri selama proses penskoran iklan menggunakan URL render materi iklan sebagai kunci. Kolom ini harus memiliki asal yang sama dengan kolom penjual. |
auctionSignals | {"category":"berita"} | Objek JSON yang dapat diserialisasi yang mewakili sinyal yang tersedia untuk semua pembeli dan penjual yang berpartisipasi dalam lelang. |
sellerSignals | {...} | Objek JSON yang dapat diserialisasi yang mewakili sinyal yang tersedia hanya untuk penjual. |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Sinyal yang tersedia untuk pembeli tertentu. Sinyal dapat berasal dari penjual dan juga oleh pembeli itu sendiri. |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Waktu proses maksimum dalam milidetik dari skrip generateBid() pembeli tertentu. Simbol karakter pengganti akan diterapkan pada setiap pembeli yang tidak memiliki waktu tunggu tertentu yang ditentukan. |
sellerTimeout | 100 | Runtime maksimum dalam milidetik dari skrip scoreAd() penjual. |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Konfigurasi tambahan untuk lelang komponen. |
resolveToConfig | benar|salah | Boolean yang mengarahkan promise yang ditampilkan dari runAdLelang() akan di-resolve ke FencedFrameConfig jika true (untuk digunakan dalam <fencedframe>), atau ke URL urn:uuid buram jika false (untuk digunakan dalam <iframe>). Nilai defaultnya adalah false. |
Memberikan sinyal secara asinkron
Nilai beberapa sinyal (yang dikonfigurasi oleh kolom auctionSignals
, sellerSignals
, perBuyerSignals
, dan perBuyerTimeouts
) secara opsional dapat diberikan bukan sebagai nilai konkret, tetapi sebagai Promise. Hal ini memungkinkan
beberapa bagian lelang, seperti pemuatan skrip dan sinyal tepercaya, serta
peluncuran proses worklet yang terisolasi, untuk tumpang-tindih dengan komputasi (atau pengambilan
jaringan) nilai tersebut. Skrip worklet hanya akan melihat nilai yang di-resolve; jika Promise tersebut ditolak, lelang akan dibatalkan kecuali jika sudah berhasil gagal atau dibatalkan dengan cara lain.
Mengonfigurasi lelang dengan beberapa penjual
Dalam beberapa kasus, beberapa penjual mungkin ingin berpartisipasi dalam lelang, dengan
pemenang lelang terpisah yang diteruskan ke lelang lain, yang dijalankan oleh penjual
lain. Lelang terpisah ini yang diteruskan disebut lelang komponen.
Untuk memfasilitasi lelang komponen ini, objek componentAuctions
dapat berisi
konfigurasi lelang tambahan untuk setiap lelang komponen penjual. Bid
yang menang dari setiap lelang komponen ini akan diteruskan ke
lelang "tingkat teratas" yang membuat penentuan akhir lelang. auctionConfig
lelang komponen mungkin tidak memiliki
componentAuctions
-nya sendiri. Jika componentAuctions
tidak kosong, interestGroupBuyers
harus kosong. Artinya, untuk lelang Protected
Audience tertentu, apakah ada satu penjual dan tidak ada lelang komponen, atau
semua bid berasal dari lelang komponen dan lelang tingkat teratas hanya dapat
memilih di antara pemenang lelang komponen.
Menjalankan lelang
Penjual membuat permintaan ke browser pengguna untuk memulai lelang iklan dengan
memanggil navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Panggilan runAdAuction()
menampilkan Promise yang di-resolve ke iklan. Kode apa pun di halaman penayang tidak dapat memeriksa iklan pemenang atau mempelajari kontennya dari hasil runAdAuction()
. Jika
flag resolveToConfig
ditetapkan ke benar (true) di AuctionConfig
, objek
FencedFrameConfig
akan ditampilkan yang hanya dapat dirender dalam frame
dengan fence. Jika tanda ini disetel ke salah (false), URN buram akan ditampilkan yang dapat
dirender dalam iframe. Ada kemungkinan bahwa runAdLelang menampilkan nilai null,
yang menunjukkan bahwa tidak ada iklan yang dipilih. Dalam hal ini, penjual dapat memilih untuk
merender iklan yang ditargetkan secara kontekstual.