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 agar latensi lelang lebih baik.

Tugas pengoptimalan payload berikut diperlukan oleh pembeli:

• joinAdInterestGroup() tugas
  • Menetapkan flag permintaan server
  • Menetapkan ID rendering iklan
  • Menetapkan prioritas grup minat
  • Menyiapkan sinyal bidding tepercaya
• generateBid() tugas
  • Membaca sinyal browser
  • URL render kembali
  • ID pelaporan pengembalian

Grup minat untuk B&A

Berikut adalah contoh konfigurasi grup minat untuk lelang PA B&A dengan pengoptimalan payload 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 auctionServerRequestFlags memungkinkan setelan tanda yang memberi tahu browser untuk menghilangkan beberapa data dalam payload lelang B&A.
• Nilai userBiddingSignals dapat ditentukan dalam grup minat, tetapi sebaiknya dihilangkan dengan menggunakan tanda omit-user-bidding-signals. Sinyal yang dihilangkan dapat diberikan 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 dalam IG.
• ID pelaporan ditentukan dalam 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 dalam IG.
• ID pelaporan dan ad.metadata tidak disertakan dalam payload lelang B&A, dan sebagai gantinya, data tersebut tersedia melalui penggunaan Layanan Kunci/Nilai Tepercaya.

Perhatikan bahwa ID pelaporan dan renderURL 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 tanda berikut:

Data yang tidak disertakan ditangani dengan menyediakan informasi yang relevan di trustedBiddingSignals. Setiap tanda dapat digunakan secara terpisah, 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 grup minat dihilangkan, dan sebagai gantinya, 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 pada 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 yang lebih rendah untuk satu pembeli saat payload lelang B&A dibuat untuk penjual. Untuk memilih grup minat di antara berbagai pembeli, browser memutuskan berdasarkan ukuran payload yang diserialisasi. Secara default, setiap pembeli diberi ukuran yang sama. Perhatikan bahwa penentuan prioritas sebenarnya terjadi di server B&A, dan bukan saat payload permintaan dibuat.

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

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

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

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 Key/Value 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

Salah satu pendekatan yang dapat dilakukan adalah menyertakan ID unik dalam kunci sinyal bidding tepercaya, lalu mengirimkan 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 ini, 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. Di 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 diikuti atau diperbarui dalam jangka 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 daripada 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 untuk 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() Perbandingan 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 baru atau yang diubah berikut tersedia di browserSignals:

Menampilkan URL render dari generateBid()

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

Salah satu pendekatan yang dapat dilakukan adalah dengan 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 mengirimkan warna favorit pengguna dan informasi produk untuk dimuat ke dalam Layanan Key/Value:

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

Di 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 tersedia untuk generateBid() melalui sinyal bidding tepercaya. Setelah ditentukan ID pelaporan mana yang akan digunakan, 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 terkaitnya 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() melalui 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

• Pelajari lebih lanjut konfigurasi lelang B&A di Chrome
• Bereksperimen dengan Protected Audience dengan B&A dengan mengikuti codelab Pengujian Lokal End-to-End.

Ada pertanyaan?

• Jika ada pertanyaan tentang Layanan Bidding dan Lelang, buka masalah di repositori Layanan B&A.