ผสานรวมกับ B&A ในฐานะผู้ซื้อ

บริการเสนอราคาและประมูล (Bidding and Auction หรือ B&A) คือชุดบริการสำหรับผู้ซื้อและผู้ขายโฆษณาที่ทำงานในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ (TEE) เพื่ออำนวยความสะดวกในการประมูล Protected Audience (PA) คู่มือสำหรับนักพัฒนาซอฟต์แวร์นี้อธิบายวิธีที่ผู้ซื้อสามารถผสานรวมกับ B&A PA Auction สำหรับ Chrome

ภาพรวม

หากต้องการเข้าร่วมการประมูลที่ใช้ Protected Audience API กับบริการ B&A ผู้ซื้อจะอัปเดตกลุ่มความสนใจ (IG) เพื่อเพิ่มประสิทธิภาพเพย์โหลดเพื่อลดเวลาในการตอบสนองของการประมูล

ผู้ซื้อกำหนดให้ต้องดำเนินการเพิ่มประสิทธิภาพเพย์โหลดต่อไปนี้

• joinAdInterestGroup() งาน
  • ตั้งค่าสถานะคำขอเซิร์ฟเวอร์
  • ตั้งค่ารหัสการแสดงโฆษณา
  • กำหนดลำดับความสำคัญของกลุ่มตามความสนใจ
  • ตั้งค่าสัญญาณการเสนอราคาที่เชื่อถือได้
• generateBid() งาน
  • อ่านสัญญาณของเบราว์เซอร์
  • URL การแสดงผลที่ส่งคืน
  • รหัสการรายงานการคืนสินค้า

กลุ่มความสนใจสำหรับ B&A

ต่อไปนี้คือตัวอย่างการกำหนดค่ากลุ่มความสนใจสำหรับการประมูล B&A PA ที่ใช้การเพิ่มประสิทธิภาพเพย์โหลด

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,
});

ความแตกต่างระหว่างการกำหนดค่า B&A กับกลุ่มความสนใจในอุปกรณ์มีดังนี้

• ฟิลด์ auctionServerRequestFlags ช่วยให้ตั้งค่าสถานะที่บอกเบราว์เซอร์ให้ละเว้นข้อมูลบางอย่างในเพย์โหลดการประมูล B&A ได้
• คุณกำหนดค่า userBiddingSignals ในกลุ่มความสนใจได้ แต่ขอแนะนำให้ละเว้นค่าดังกล่าวโดยใช้แฟล็ก omit-user-bidding-signals คุณระบุสัญญาณที่ละเว้นได้โดยใช้บริการ K/V
• ฟิลด์ adRenderId จะได้รับการตั้งค่าพร้อมกับ renderURL ที่เกี่ยวข้อง แต่จะมีเพียง adRenderId เท่านั้นที่จะกลายเป็นส่วนหนึ่งของเพย์โหลดการประมูล B&A URL การแสดงผลที่ส่งคืนจาก generateBid() ในภายหลังระหว่างเวลาการประมูลต้องตรงกับ URL การแสดงผลที่กำหนดไว้ใน IG
• ระบบจะกําหนดรหัสการรายงานใน IG ของ B&A แต่จะไม่รวมไว้ในเพย์โหลดการประมูล B&A รหัสการรายงานที่ส่งคืนจาก generateBid() ในภายหลังระหว่างเวลาการประมูลต้องตรงกับ URL การแสดงผลที่กำหนดไว้ใน IG
• ad.metadata และรหัสการรายงานจะไม่รวมอยู่ในเพย์โหลดการประมูล B&A แต่ข้อมูลเหล่านั้นจะพร้อมใช้งานผ่านการใช้งานบริการคีย์/ค่าที่เชื่อถือได้แทน

โปรดทราบว่า renderURL และรหัสการรายงานใน ads ยังคงกำหนดไว้ในการกำหนดค่ากลุ่มความสนใจ แม้ว่าจะไม่ได้รวมไว้ในเพย์โหลดคำขอประมูล เนื่องจากเบราว์เซอร์จะตรวจสอบว่า URL การแสดงผลและรหัสการรายงานที่ส่งคืนจากฟังก์ชัน generateBid() ของบริการเสนอราคาตรงกับค่าที่กำหนดไว้ในกลุ่มความสนใจ

joinAdInterestGroup() งาน

คุณต้องดำเนินการต่อไปนี้สำหรับการเรียก joinAdInterestGroup()

ตั้งค่าสถานะคำขอเซิร์ฟเวอร์

ฟิลด์ joinAdInterestGroup() config's auctionServerRequestFlags ยอมรับค่าสถานะต่อไปนี้

ระบบจะจัดการข้อมูลที่ละเว้นโดยการให้ข้อมูลที่เกี่ยวข้องใน trustedBiddingSignals คุณใช้ฟีเจอร์นี้แยกกันได้ และไม่จำเป็นต้องใช้ร่วมกัน

ตัวอย่างการใช้งาน

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

ตั้งค่ารหัสการแสดงโฆษณา

เราจะละเว้นออบเจ็กต์ ads และ adComponents ของกลุ่มความสนใจเพื่อลดขนาดเพย์โหลดการประมูล B&A และออบเจ็กต์เหล่านี้จะไม่มีอยู่ในฟังก์ชัน generateBid() ที่ทำงานใน Bidding Service

ผู้ซื้อจะเก็บตัวระบุ (adRenderId และ adComponentRenderId) ที่เชื่อมโยงกับโฆษณาแต่ละรายการในการกำหนดค่ากลุ่มความสนใจไว้เพื่อจัดการข้อมูลโฆษณาที่ขาดหายไป ตัวระบุต้องเป็น DOMString ที่มีความยาวไม่เกิน 12 ไบต์ หากตัวระบุเข้ารหัส Base64 ความยาวต้องไม่เกิน 12 ไบต์

ตัวอย่างกลุ่มความสนใจที่มีรหัสการแสดงโฆษณา

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 ที่เชื่อมโยงกับโฆษณาจะพร้อมใช้งานใน prevWins.browserSignals ใน generateBid()

แม้ว่าจะไม่ได้รวม renderURL ไว้ในเพย์โหลดคำขอ แต่ URL การแสดงผลที่ส่งคืนจาก generateBid() ต้องตรงกับ URL การแสดงผลที่กำหนดไว้ในการกำหนดค่ากลุ่มความสนใจ เทคโนโลยีโฆษณาสามารถส่งข้อมูลเมตาของโฆษณาและข้อมูลอื่นๆ กลับมาใน trustedBiddingSignals เพื่อให้สร้าง URL การแสดงโฆษณาและ URL การแสดงคอมโพเนนต์โฆษณาสำหรับการเสนอราคาในระหว่างการดำเนินการ generateBid() ได้

กำหนดลำดับความสำคัญของกลุ่มความสนใจ

Chrome อนุญาตให้ผู้ซื้อจัดลำดับความสำคัญของกลุ่มความสนใจ หากถึงขีดจำกัดขนาดเพย์โหลดต่อผู้ซื้อที่ผู้ขายกำหนดไว้ ระบบจะใช้ค่าลำดับความสำคัญของกลุ่มความสนใจเพื่อทิ้งกลุ่มความสนใจที่มีลำดับความสำคัญต่ำกว่าสำหรับผู้ซื้อรายเดียวเมื่อสร้างเพย์โหลดการประมูล B&A สำหรับผู้ขาย สำหรับการเลือกกลุ่มความสนใจระหว่างผู้ซื้อรายต่างๆ เบราว์เซอร์จะตัดสินใจโดยอิงตามขนาดของเพย์โหลดที่แปลงเป็นอนุกรม โดยค่าเริ่มต้น ระบบจะกำหนดขนาดเท่ากันให้กับผู้ซื้อแต่ละราย โปรดทราบว่าการจัดลําดับความสําคัญที่แท้จริงจะเกิดขึ้นในเซิร์ฟเวอร์ B&A ไม่ใช่เมื่อสร้างเพย์โหลดของคําขอ

ระบบจะคำนวณลำดับความสำคัญในเวลาที่ประมูลโดยใช้เวกเตอร์ลำดับความสำคัญของผู้ซื้อ (priorityVector) และสัญญาณลำดับความสำคัญของผู้ขาย (prioritySignals) ผู้ซื้อมีสิทธิ์ลบล้างสัญญาณลำดับความสำคัญของผู้ขาย

ในระหว่างการประมูล เบราว์เซอร์จะคำนวณดอทโปรดักต์แบบกระจัดกระจายของคีย์ที่ตรงกันใน priorityVector และ prioritySignals สำหรับลำดับความสำคัญ ในแผนภาพต่อไปนี้ ระบบจะคำนวณลำดับความสำคัญโดย (4 * 2) + (3 * -1) ซึ่งลดลงเหลือ 8 + -3 ดังนั้นลำดับความสำคัญของกลุ่มความสนใจนี้ในเวลาที่ประมูลคือ 5

นอกจากนี้ ยังมีสัญญาณเพิ่มเติมที่ใช้ในการจัดลําดับความสําคัญใน B&A ได้ด้วย ดังนี้

ดูข้อมูลเพิ่มเติมได้ที่คำอธิบายใน GitHub

ตั้งค่าสัญญาณการเสนอราคาที่เชื่อถือได้

เนื่องจากระบบจะละเว้นข้อมูลบางอย่างจากเพย์โหลดการประมูล B&A คุณจึงใช้บริการคีย์/ค่าเพื่อระบุข้อมูลที่ละเว้นเป็นสัญญาณการเสนอราคาที่เชื่อถือได้ให้กับฟังก์ชัน generateBid() ได้

บริการ K/V สามารถให้ข้อมูลต่อไปนี้ที่ถูกละเว้นได้

• userBiddingSignals หากผู้ซื้อใช้
• metadata ที่เชื่อมโยงกับโฆษณาแต่ละรายการ
• adRenderId ที่เชื่อมโยงกับโฆษณาแต่ละรายการ
• รหัสการรายงาน

แนวทางหนึ่งที่สามารถใช้ได้คือการใส่ตัวระบุที่ไม่ซ้ำกันในคีย์สัญญาณการเสนอราคาที่เชื่อถือได้ แล้วส่งข้อมูลที่เชื่อมโยงไปยังเซิร์ฟเวอร์เพื่อให้โหลดลงในบริการคีย์/ค่าได้ อย่างไรก็ตาม การติดตั้งใช้งานจริงขึ้นอยู่กับเทคโนโลยีโฆษณา และ API ไม่ได้กำหนดไว้

ตัวอย่างต่อไปนี้อธิบายแนวทางหนึ่งที่สามารถนำไปใช้ได้

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'
          }   
        },
      ]
    }
  })
});

ในตัวอย่างนี้ ระบบจะกำหนดตัวระบุที่ไม่ซ้ำกันสำหรับ IG และกลายเป็นส่วนหนึ่งของคีย์สัญญาณที่เชื่อถือได้ ระบบจะส่งคีย์สำหรับ IG และค่าที่เกี่ยวข้องไปยังเซิร์ฟเวอร์ของคุณเพื่อโหลดลงในบริการคีย์/ค่า ในภายหลังระหว่างการประมูล เบราว์เซอร์จะดึงสัญญาณที่เชื่อถือได้และทำให้พร้อมใช้งานในฟังก์ชัน generateBid() ของผู้ซื้อ

ส่งสัญญาณการอัปเดตกลุ่มความสนใจจาก K/V หากจำเป็น

ระบบจะใช้updateIfOlderThanMsคีย์สำหรับสัญญาณที่เชื่อถือได้เพื่ออัปเดตกลุ่มความสนใจเร็วกว่าช่วงเวลาปกติในแต่ละวัน หากไม่ได้เข้าร่วมหรืออัปเดตกลุ่มความสนใจในช่วงระยะเวลาที่เกินค่ามิลลิวินาทีที่แสดงผลสำหรับคีย์ updateIfOlderThanMs ระบบจะอัปเดตกลุ่มความสนใจด้วยกลไก updateURL โปรดทราบว่า Chrome จะอัปเดตกลุ่มความสนใจไม่บ่อยกว่า 1 ครั้งทุกๆ 10 นาที

หากการประมูล B&A แสดงโฆษณาที่ชนะซึ่งไม่ตรงกับโฆษณาที่กำหนดไว้ในกลุ่มความสนใจที่จัดเก็บไว้ในเบราว์เซอร์ เบราว์เซอร์จะทำให้การประมูลล้มเหลว updateIfOlderThanMs กลไกนี้มีประโยชน์ในการตรวจสอบว่าเบราว์เซอร์และการประมูล B&A เห็นพ้องต้องกันเกี่ยวกับชุดโฆษณาในกลุ่มความสนใจ

ดูข้อมูลเพิ่มเติมได้ที่คำอธิบาย

generateBid() งาน

คุณต้องดำเนินการต่อไปนี้สำหรับการเรียก generateBid()

อ่านสัญญาณเบราว์เซอร์

ออบเจ็กต์ browserSignals ที่ส่งไปยังการเรียกใช้ B&A generateBid() มีลักษณะดังนี้

{
  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,
}

พร็อพเพอร์ตี้ที่แก้ไขหรือใหม่ต่อไปนี้พร้อมใช้งานใน browserSignals

ส่งคืน URL การแสดงผลจาก generateBid()

เนื่องจากออบเจ็กต์ ads ถูกละเว้นในเพย์โหลดการประมูล B&A จึงต้องสร้าง URL การแสดงผลที่ได้จาก generateBid() ขึ้นใหม่ ระบบจะกำหนดวิธีสร้าง URL การแสดงผลขึ้นใหม่ตามการติดตั้งใช้งานของคุณ และ URL ที่แสดงผลจะต้องตรงกับ URL การแสดงผลที่กำหนดไว้ในกลุ่มความสนใจ

วิธีหนึ่งที่ทำได้คือการรักษา URL ฐานไว้ และป้อนข้อมูลจาก interestGroup และ trustedBiddingSignals ลงในเทมเพลต

ในตัวอย่างนี้ เราจะกำหนดโฆษณา 4 รายการตามสีและผลิตภัณฑ์ ดังนี้

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
  ]
})

จากนั้นเราจะส่งสีที่ผู้ใช้ชื่นชอบและข้อมูลผลิตภัณฑ์เพื่อโหลดลงในบริการคีย์/ค่า

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

ในภายหลัง เมื่อการประมูลทํางาน สัญญาณการเสนอราคาที่เชื่อถือได้จะพร้อมใช้งานใน generateBid() และสามารถใช้ข้อมูลดังกล่าวเพื่อสร้าง URL ใหม่ได้

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

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

ส่งคืนรหัสการรายงานจาก generateBid()

เนื่องจากไม่ได้รวมรหัสการรายงานไว้ในเพย์โหลดการประมูล B&A รหัสจึงพร้อมใช้งานสำหรับ generateBid() ผ่านสัญญาณการเสนอราคาที่เชื่อถือได้ เมื่อกำหนดแล้วว่าจะใช้รหัสการรายงานใด generateBid() จะแสดงรหัสการรายงานที่เลือก รหัสที่แสดงต้องตรงกับรหัสที่กำหนดไว้ในกลุ่มความสนใจ

ในตัวอย่างนี้ ระบบเลือกโฆษณา 1 และแสดงรหัสการแสดงผลที่เชื่อมโยงจาก generateBid()

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

รหัสการรายงานที่ส่งกลับมาจะพร้อมใช้งานใน reportWin() ถึง buyerReportingSignals

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

หาก generateBid() ไม่แสดงผล buyerReportingId ค่า interestGroupName จะอยู่ใน buyerReportingSignals แทน buyerReportingId

ดูข้อมูลเพิ่มเติมได้ที่คู่มือการรายงานรหัส

ขั้นตอนถัดไป

แหล่งข้อมูลต่อไปนี้พร้อมให้บริการแก่คุณ

ดูข้อมูลเพิ่มเติม

• ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าการประมูล B&A ใน Chrome
• ทดสอบ Protected Audience ด้วย B&A โดยทำตาม Codelab การทดสอบในเครื่องแบบครบวงจร

หากมีคำถาม

• หากมีคำถามเกี่ยวกับบริการการเสนอราคาและการประมูล โปรดเปิดปัญหาในที่เก็บบริการ B&A