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 menyebut pihak yang menjalankan lelang sebagai penjual. Banyak pihak yang dapat bertindak sebagai penjual: situs dapat menjalankan lelang iklannya sendiri, atau dapat menyertakan skrip pihak ketiga untuk menjalankan lelang tersebut, atau dapat menggunakan SSP yang menggabungkan pelaksanaan lelang di perangkat dengan aktivitas lelang iklan sisi server lainnya. Penjual memiliki tiga tugas dasar dalam lelang iklan di perangkat:

  1. Penjual memutuskan (a) pembeli mana yang dapat berpartisipasi, dan (b) bid mana dari grup minat pembeli tersebut yang memenuhi syarat untuk mengikuti lelang. Hal ini memungkinkan penjual 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 "daya tarik". Bid dengan skor keinginan tertinggi akan memenangkan lelang.
  3. Penjual melakukan pelaporan hasil lelang, termasuk informasi tentang harga penyelesaian 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 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],
};

Properti AuctionConfig

Properti wajib

Satu-satunya properti yang wajib diisi untuk auctionConfigs adalah seller, decisionLogicUrl, dan interestGroupBuyers.

Properti Contoh Peran
seller https://seller.example Asal penjual.
decisionLogicUrl https://seller.example/decision-logic.js URL untuk worklet logika keputusan JavaScript lelang. Kolom ini harus memiliki origin yang sama dengan kolom penjual.
interestGroupBuyers [https://buyer-1.example,
https://buyer-2.example,
...]		 Asal semua pemilik grup minat yang diminta untuk mengajukan bid dalam lelang

Properti opsional

Properti yang tersisa untuk auctionConfigs bersifat opsional.

Properti Contoh Peran
trustedScoringSignalsUrl https://seller.example/scoring-signals URL server Key/Value penjual. Nilai ini akan dikueri selama proses pemberian skor iklan menggunakan URL render materi iklan sebagai kuncinya. Kolom ini harus memiliki origin yang sama dengan kolom penjual.
auctionSignals {"category":"news"} Objek yang dapat diserialisasi JSON yang merepresentasikan sinyal yang tersedia untuk semua pembeli dan penjual yang berpartisipasi dalam lelang.
sellerSignals {...} Objek yang dapat diserialisasi JSON yang merepresentasikan sinyal yang hanya tersedia untuk penjual.
perBuyerSignals {https://dsp.example: {...},
https://another-buyer.example: {...},
... }		 Sinyal yang tersedia untuk pembeli tertentu. Sinyal dapat berasal dari penjual dan juga dari pembeli itu sendiri.
perBuyerTimeouts {https://www.example-dsp.com: 50,
https://www.another-buyer.com: 200,
*: 150,
...},		 Waktu proses maksimum dalam milidetik untuk skrip generateBid() pembeli tertentu. Simbol karakter pengganti akan diterapkan ke setiap pembeli yang tidak memiliki waktu tunggu tertentu yang ditentukan.
sellerTimeout 100 Waktu proses maksimum dalam milidetik untuk skrip scoreAd() penjual.
componentAuctions [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] Konfigurasi tambahan untuk lelang komponen.
resolveToConfig true|false Nilai boolean yang mengarahkan promise yang ditampilkan dari runAdAuction() agar diselesaikan ke FencedFrameConfig jika benar (untuk digunakan dalam <fencedframe>), atau ke URL urn:uuid buram jika salah (untuk digunakan dalam <iframe>). Nilai defaultnya adalah salah.

Menyediakan sinyal secara asinkron

Nilai beberapa sinyal (yang dikonfigurasi oleh kolom auctionSignals, sellerSignals, perBuyerSignals, dan perBuyerTimeouts) dapat secara opsional diberikan bukan sebagai nilai konkret, tetapi sebagai Promise. Hal ini memungkinkan beberapa bagian lelang, seperti pemuatan skrip dan sinyal tepercaya, serta peluncuran proses worklet terisolasi, untuk tumpang-tindih dengan komputasi (atau pengambilan jaringan) nilai tersebut. Skrip worklet hanya akan melihat nilai yang telah diselesaikan; jika Promise tersebut ditolak, lelang akan dibatalkan kecuali jika lelang tersebut sudah 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 yang diteruskan ini disebut lelang komponen. Untuk memfasilitasi lelang komponen ini, objek componentAuctions dapat berisi konfigurasi lelang tambahan untuk setiap lelang komponen penjual. Bid yang menang di setiap lelang komponen ini akan diteruskan ke lelang "tingkat teratas" yang membuat penentuan akhir lelang. auctionConfig lelang komponen mungkin tidak memiliki componentAuctions sendiri. Jika componentAuctions tidak kosong, interestGroupBuyers harus kosong. Artinya, untuk lelang Protected Audience tertentu, hanya 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 isinya dari hasil runAdAuction(). Jika tanda resolveToConfig disetel ke benar (true) di AuctionConfig, objek FencedFrameConfig akan ditampilkan yang hanya dapat dirender dalam frame tertutup. Jika tanda disetel ke salah (false), URN buram akan ditampilkan yang dapat dirender dalam iframe. Ada kemungkinan bahwa runAdAuction menampilkan nilai null, yang menunjukkan bahwa tidak ada iklan yang dipilih. Dalam hal ini, penjual dapat memilih untuk merender iklan yang ditargetkan secara kontekstual.