Menyiapkan lelang iklan di halaman penayang

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:

1. 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.
2. 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.
3. 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

Catatan: additionalBids tidak didukung dalam penerapan Protected Audience API saat ini. Baca bagian Peserta Lelang di penjelasan Protected Audience API untuk mengetahui informasi selengkapnya.

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.