Menyiapkan lelang iklan di halaman penayang

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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 mungkin bertindak sebagai penjual: situs mungkin menjalankan lelang iklannya sendiri atau mungkin menyertakan pihak ketiga untuk menjalankan lelang bagi lelang tersebut, atau mungkin menggunakan SSP yang menggabungkan menjalankan 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) penawaran yang mana dari grup minat yang memenuhi syarat untuk mengikuti lelang. Hal ini memungkinkan penjual menerapkan aturan situs tentang iklan yang boleh tampil di kami.
2. Penjual bertanggung jawab atas logika bisnis lelang: JavaScript kode yang mempertimbangkan harga dan metadata setiap bid, serta menghitung "keinginan" skor. Bid dengan skor keinginan tertinggi akan memenangkan lelang.
3. Penjual melakukan pelaporan tentang hasil lelang, termasuk informasi tentang kliring harga dan pembayaran lainnya. Pembeli yang menang dan kalah juga akan untuk 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 opsional

Properti lainnya untuk auctionConfigs bersifat opsional.

Memberikan sinyal secara asinkron

Nilai beberapa sinyal (yang dikonfigurasi oleh auctionSignals, sellerSignals, perBuyerSignals, dan perBuyerTimeouts) dapat secara opsional diberikan sebagai nilai konkret, bukan sebagai Promise. Ini mengizinkan beberapa bagian lelang, seperti pemuatan skrip dan sinyal tepercaya, serta peluncuran proses worklet terpisah, untuk tumpang tindih dengan komputasi (atau jaringan yang hilang) dari nilai-nilai tersebut. Skrip worklet hanya akan melihat respons nilai-nilai; jika Promise semacam itu ditolak, lelang akan dibatalkan kecuali jika Promise tersebut ditolak 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, dijalankan oleh lelang lain penjual. Lelang terpisah yang dilewati ini disebut lelang komponen. Untuk memfasilitasi lelang komponen ini, objek componentAuctions dapat berisi konfigurasi lelang tambahan untuk setiap lelang komponen penjual. Tujuan yang menang dari setiap lelang komponen ini akan diteruskan ke "tingkat teratas" lelang yang membuat keputusan akhir lelang. Tujuan auctionConfig lelang komponen mungkin tidak memiliki lelang sendiri componentAuctions. Jika componentAuctions tidak kosong, interestGroupBuyers harus kosong. Artinya, untuk setiap kasus Lelang audiens, baik ada satu penjual dan tidak ada lelang komponen, atau Jika tidak, semua bid berasal dari lelang komponen dan lelang tingkat teratas hanya bisa memilih di antara lelang komponen pemenang penghargaan.

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. Tidak kode apa pun di halaman penayang untuk memeriksa iklan pemenang atau jika tidak, pelajari kontennya dari hasil runAdAuction(). Jika Flag resolveToConfig ditetapkan ke benar (true) di AuctionConfig, yaitu Objek FencedFrameConfig ditampilkan, yang hanya dapat dirender dalam fence {i>frame<i}. Jika penanda disetel ke false, maka URN buram akan ditampilkan, yang dapat dirender dalam iframe. Ada kemungkinan runAdLelang menampilkan nilai null, yang menunjukkan bahwa tidak ada iklan yang dipilih. Dalam hal ini penjual mungkin memilih untuk menampilkan iklan bertarget kontekstual.