Berintegrasi dengan B&A sebagai pembeli

Layanan Bidding dan Lelang (B&A) adalah serangkaian layanan untuk pembeli dan penjual iklan yang berjalan di Trusted Execution Environment (TEE) untuk memfasilitasi lelang Protected Audience (PA). Panduan Developer ini menjelaskan cara pembeli dapat berintegrasi dengan lelang PA B&A untuk Chrome.

Ringkasan

Untuk berpartisipasi dalam lelang Protected Audience dengan Layanan B&A, pembeli memperbarui grup minat (IG) untuk mengoptimalkan payload guna meningkatkan latensi lelang.

Tugas pengoptimalan payload berikut diperlukan oleh pembeli:

Grup minat untuk B&A

Berikut adalah contoh konfigurasi grup minat untuk lelang PA B&A dengan pengoptimalan payload yang diterapkan:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

Perbedaan antara konfigurasi grup minat B&A dan di perangkat adalah:

Kolom IG B&A IG di perangkat Disertakan dalam payload lelang B&A
auctionServerRequestFlags Bekas Tidak digunakan Tidak
userBiddingSignals Tidak direkomendasikan Bekas Tidak, jika tanda omit-user-bidding-signals ditetapkan
adRenderId di ads dan adComponents Bekas Tidak digunakan Jika flag omit-ads ditetapkan, adRenderId di ads hanya tersedia di browserSignals.prevWins payload. adRenderId yang ditentukan dalam adComponents tidak disertakan dalam payload.

Jika tanda omit-ads tidak ditetapkan, tersedia di browserSignals.prevWins, interestGroup.adRenderIds, dan interestGroup.adComponentRenderIds.
renderURL di ads dan adComponents Bekas Bekas Tidak
metadata di ads dan adComponents Tidak digunakan Bekas Tidak
ID pelaporan di ads Bekas Bekas Tidak
  • Kolom auctionServerRequestFlags memungkinkan penetapan flag yang memberi tahu browser untuk menghapus beberapa data dalam payload lelang B&A.
  • Nilai userBiddingSignals dapat ditentukan dalam grup minat, tetapi sebaiknya hapus nilai tersebut menggunakan tanda omit-user-bidding-signals. Sinyal yang dihilangkan dapat disediakan menggunakan Layanan K/V.
  • Kolom adRenderId ditetapkan bersama dengan renderURL terkait, tetapi hanya adRenderId yang akan menjadi bagian dari payload lelang B&A. URL render yang ditampilkan dari generateBid() nanti selama waktu lelang harus cocok dengan URL render yang ditentukan di IG.
  • ID pelaporan ditentukan di IG B&A, tetapi tidak disertakan dalam payload lelang B&A. ID pelaporan yang ditampilkan dari generateBid() nanti selama waktu lelang harus cocok dengan URL render yang ditentukan di IG.
  • ad.metadata dan ID pelaporan tidak disertakan dalam payload lelang B&A, dan sebagai gantinya, data tersebut akan tersedia melalui penggunaan Layanan Kunci/Nilai Tepercaya.

Perhatikan bahwa renderURL dan ID pelaporan di ads masih ditentukan dalam konfigurasi grup minat, meskipun tidak disertakan dalam payload permintaan lelang, karena browser memeriksa apakah URL render dan ID pelaporan yang ditampilkan dari fungsi generateBid() Layanan Bidding cocok dengan nilai yang ditentukan dalam grup minat.

joinAdInterestGroup() tugas

Tugas berikut perlu dilakukan untuk panggilan joinAdInterestGroup().

Menetapkan flag permintaan server

Kolom auctionServerRequestFlags konfigurasi joinAdInterestGroup() menerima flag berikut:

Flag Deskripsi
omit-user-bidding-signals Flag omit-user-bidding-signals menghilangkan objek userBiddingSignals dalam payload lelang.

Jika flag tidak ditetapkan, nilai userBiddingSignals yang ditentukan dalam grup minat akan tersedia di dalam generateBid() Layanan Bidding.
omit-ads Flag omit-ads memberi tahu browser untuk menghapus objek ads dan adComponents dalam payload lelang.

adRenderId akan tersedia di properti prevWins dari browserSignals.

Jika flag tidak ditetapkan, kolom adRenderIds dan adComponentRenderIds dalam argumen interestGroup dari generateBid() akan berisi ID rendering iklan yang sesuai.

Sebaiknya pembeli memilih flag omit-ads. Pada masa mendatang, meneruskan ID render dan ID render komponen iklan dari klien mungkin tidak digunakan lagi untuk pengoptimalan payload lebih lanjut.

Data yang dihilangkan ditangani dengan menyediakan informasi yang relevan di trustedBiddingSignals. Flag dapat digunakan satu per satu, dan tidak harus digunakan bersama.

Contoh penggunaan:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

Menetapkan ID rendering iklan

Untuk mengurangi ukuran payload lelang B&A, objek ads dan adComponents dari grup minat dihilangkan, dan pada akhirnya, objek ini tidak tersedia di dalam fungsi generateBid() yang berjalan di Layanan Bidding.

Untuk menangani informasi iklan yang tidak ada, pembeli mempertahankan ID (adRenderId dan adComponentRenderId) yang terkait dengan setiap iklan dalam konfigurasi grup minat. ID harus berupa DOMString yang panjangnya 12 byte atau kurang. Jika ID dienkode Base64, panjangnya harus 12 byte atau kurang.

Contoh grup minat dengan ID rendering iklan:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

adRenderId yang terkait dengan iklan akan tersedia di prevWins.browserSignals di generateBid().

Meskipun renderURL tidak disertakan dalam payload permintaan, URL render yang ditampilkan dari generateBid() harus cocok dengan URL render yang ditentukan dalam konfigurasi grup minat. Teknologi iklan dapat mengirim kembali metadata iklan dan informasi lainnya di trustedBiddingSignals, sehingga URL render iklan dan URL render komponen iklan dapat dibuat untuk bid selama eksekusi generateBid().

Menetapkan prioritas grup minat

Chrome memungkinkan pembeli memprioritaskan grup minat. Jika batas ukuran payload per pembeli yang ditetapkan oleh penjual tercapai, nilai prioritas grup minat akan digunakan untuk menghapus grup minat dengan prioritas lebih rendah untuk satu pembeli saat payload lelang B&A dibuat untuk penjual. Untuk memilih grup minat di antara pembeli yang berbeda, browser memutuskan berdasarkan ukuran payload yang diserialisasi. Secara default, setiap pembeli diberi ukuran yang sama. Perhatikan bahwa prioritas sebenarnya terjadi di server B&A, bukan saat payload permintaan dibuat.

Prioritas dihitung pada waktu lelang menggunakan vektor prioritas pembeli (priorityVector) dan sinyal prioritas penjual (prioritySignals). Pembeli memiliki kemampuan untuk mengganti sinyal prioritas penjual.

Properti Deskripsi
Vektor prioritas Pembeli menyediakan vektor sebagai nilai kunci priorityVector dari Layanan K/V
Sinyal prioritas Penjual menyediakan sinyal dengan menetapkan priority_signals dari konfigurasi lelang
Penggantian sinyal prioritas Pembeli memberikan penggantian di kolom priority_signals_overrides dari PerBuyerConfig dalam konfigurasi lelang.

Selama lelang, browser menghitung perkalian titik jarang dari kunci yang cocok di priorityVector dan prioritySignals untuk prioritas. Dalam diagram berikut, prioritas dihitung dengan (4 * 2) + (3 * -1) yang dikurangi menjadi 8 + -3, sehingga prioritas grup minat ini pada waktu lelang adalah 5.

Setiap kunci dalam objek vektor prioritas dan sinyal prioritas dikalikan satu sama lain, lalu hasilnya dijumlahkan untuk menghitung prioritas
Gambar 1: Penghitungan prioritas menggunakan vektor pembeli dan sinyal penjual

Sinyal tambahan juga tersedia untuk digunakan dalam penentuan prioritas di B&A:

Sinyal Deskripsi
deviceSignals.one Nilainya selalu 1, dan berguna untuk menambahkan konstanta ke hasil perkalian titik.
deviceSignals.ageInMinutes Nilai ini menjelaskan usia grup minat (waktu sejak grup minat terbaru bergabung) dalam menit sebagai bilangan bulat antara 0 dan 43.200.
deviceSignals.ageInMinutesMax60 Nilainya sama dengan sinyal ageInMinutes, tetapi maksimumnya 60. Jika grup sudah lebih dari 1 jam, 60 akan ditampilkan.
deviceSignals.ageInHoursMax24 Nilai ini menjelaskan usia grup minat dalam jam, dengan maksimum 24 jam. Jika grup sudah lebih dari satu hari, 24 akan ditampilkan.
deviceSignals.ageInDaysMax30 Nilai ini menjelaskan usia grup minat dalam hari, maksimal 30 hari. Jika grup sudah lebih dari 30 hari, 30 akan ditampilkan.

Untuk mempelajari lebih lanjut, buka penjelasan di GitHub.

Menyiapkan sinyal bidding tepercaya

Karena beberapa data akan dihilangkan dari payload lelang B&A, Anda dapat menggunakan Layanan Nilai Kunci untuk menyediakan data yang dihilangkan sebagai sinyal bidding tepercaya ke fungsi generateBid().

Data yang dihilangkan berikut dapat disediakan oleh Layanan K/V:

  • userBiddingSignals jika digunakan oleh pembeli
  • metadata yang terkait dengan setiap iklan
  • adRenderId yang terkait dengan setiap iklan
  • ID Pelaporan
Data yang dihilangkan dari grup minat dapat dikirim ke server pengumpulan pembeli. Server koleksi mendorong data ke layanan nilai kunci, dan pada lain waktu, browser memuat data tersebut dari layanan nilai kunci
Gambar 2: Contoh penyiapan sinyal tepercaya

Salah satu pendekatan yang dapat dilakukan adalah menyertakan ID unik dalam kunci sinyal bidding tepercaya, lalu mengirim data terkait ke server Anda agar dapat dimuat ke dalam Layanan Kunci/Nilai. Namun, implementasi sebenarnya bergantung pada teknologi iklan dan API tidak bersifat preskriptif.

Contoh berikut menjelaskan salah satu pendekatan yang dapat diterapkan:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

Dalam contoh, ID unik ditentukan untuk IG dan menjadi bagian dari kunci sinyal tepercaya. Kunci untuk IG dan nilai terkaitnya dikirim ke server Anda untuk dimuat ke dalam Layanan Kunci/Nilai. Pada lain waktu selama lelang, browser mengambil sinyal tepercaya dan menyediakannya di fungsi generateBid() pembeli.

Menampilkan sinyal pembaruan grup minat dari K/V jika diperlukan

Kunci updateIfOlderThanMs untuk sinyal tepercaya digunakan untuk memperbarui grup minat lebih awal dari interval harian biasanya. Jika grup minat belum digabungkan atau diperbarui dalam durasi waktu yang melebihi nilai milidetik yang ditampilkan untuk kunci updateIfOlderThanMs, grup minat akan diperbarui dengan mekanisme updateURL. Perhatikan bahwa Chrome tidak akan memperbarui grup minat lebih sering dari sekali setiap 10 menit.

Jika lelang B&A menampilkan iklan pemenang yang tidak cocok dengan salah satu iklan yang ditentukan dalam grup minat yang disimpan di browser, browser akan gagal dalam lelang. Mekanisme updateIfOlderThanMs dapat berguna dalam memastikan bahwa browser dan lelang B&A menyetujui kumpulan iklan dalam grup minat.

Buka penjelasan untuk mempelajari lebih lanjut.

generateBid() tugas

Tugas berikut perlu dilakukan untuk panggilan generateBid().

Membaca sinyal browser

Objek browserSignals yang diteruskan ke panggilan generateBid() B&A terlihat seperti berikut:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

Properti yang diubah atau baru berikut tersedia di browserSignals:

Properti Deskripsi
prevWins prevWins adalah array tuple waktu dan iklan. Waktu ini menunjukkan detik yang berlalu sejak kemenangan sebelumnya dari iklan terkait dalam 30 hari terakhir.

Objek ini telah diubah untuk menyediakan adRenderId, bukan objek ad.
wasmHelper Objek yang dikompilasi dari kode yang disediakan dari biddingWasmHelperURL.
dataVersion Server tepercaya dapat menyertakan header respons Data-Version numerik secara opsional yang tersedia di generateBid().

Baca penjelasan di GitHub untuk mempelajari lebih lanjut.

Menampilkan URL render dari generateBid()

Karena objek ads dihilangkan dalam payload lelang B&A, URL render yang ditampilkan dari generateBid() harus dibuat ulang. Cara pembuatan ulang URL render ditentukan oleh implementasi Anda, dan URL yang ditampilkan harus cocok dengan URL render yang ditentukan dalam grup minat.

Salah satu pendekatan yang dapat dilakukan adalah mempertahankan URL dasar, dan mengisi template dengan informasi dari interestGroup dan trustedBiddingSignals.

Dalam contoh ini, kita menentukan 4 iklan berdasarkan warna dan produk:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

Kemudian, kita mengirim warna favorit dan informasi produk pengguna untuk dimuat ke dalam Layanan Kunci/Nilai:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

Pada lain waktu, saat lelang berjalan, sinyal bidding tepercaya akan tersedia di generateBid(), dan informasi tersebut dapat digunakan untuk merekonstruksi URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

Menampilkan ID pelaporan dari generateBid()

Karena ID pelaporan tidak disertakan dalam payload lelang B&A, ID tersebut akan tersedia untuk generateBid() melalui sinyal bidding tepercaya. Setelah ID pelaporan yang akan digunakan ditentukan, ID pelaporan yang dipilih akan ditampilkan dari generateBid(). ID yang ditampilkan harus cocok dengan ID yang ditentukan dalam grup minat.

Dalam contoh ini, iklan 1 dipilih, dan ID render terkait ditampilkan dari generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

ID pelaporan yang ditampilkan akan tersedia di reportWin() hingga buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

Jika buyerReportingId tidak ditampilkan dari generateBid(), nilai interestGroupName akan tersedia di buyerReportingSignals, bukan buyerReportingId.

Buka Panduan ID pelaporan untuk mempelajari lebih lanjut.

Langkah berikutnya

Referensi berikut tersedia untuk Anda

Pelajari lebih lanjut

Ada pertanyaan?