คู่มือผู้ขาย: ดำเนินการประมูลเพื่อแสดงโฆษณา

คู่มือและข้อมูลอ้างอิงเกี่ยวกับ Seller API สําหรับการประมูลโฆษณา Protected Audience API

บทความนี้จะแสดงข้อมูลอ้างอิงทางเทคนิคสําหรับการประมูลโฆษณาตามที่ใช้ใน Protected Audience API เวอร์ชันทดลองในปัจจุบัน

อ่านคู่มือนักพัฒนาซอฟต์แวร์เพื่อดูวงจรการทํางานทั้งหมดของ Protected Audience API และดูคําอธิบาย Protected Audience API เพื่อดูการพูดคุยเชิงลึกเกี่ยวกับวิธีที่ผู้ขายทําการประมูลบนอุปกรณ์

หากไม่ใช่นักพัฒนาแอป โปรดดูภาพรวมของ Protected Audience API

การประมูลโฆษณา Protected Audience API คืออะไร

การประมูลเพื่อแสดงโฆษณาของ Protected Audience API คือคอลเล็กชันโปรแกรม JavaScript ขนาดเล็กที่เบราว์เซอร์เรียกใช้บนอุปกรณ์ของผู้ใช้เพื่อเลือกโฆษณา โค้ดการประมูลโฆษณาทั้งหมดจากผู้ขายและผู้ซื้อจะทํางานใน worklet JavaScript ที่แยกต่างหาก ซึ่งไม่สามารถสื่อสารกับโลกภายนอกได้ เพื่อรักษาความเป็นส่วนตัว

6 ระยะในการประมูลโฆษณา Protected Audience API
แผนภาพนี้แสดงภาพรวมแต่ละระยะของการประมูลโฆษณา Protected Audience API
  1. ผู้ใช้เข้าชมเว็บไซต์ที่แสดงโฆษณา
  2. โค้ดของผู้ขายจะเรียกใช้ navigator.runAdAuction() ซึ่งจะระบุพื้นที่โฆษณาที่ขายได้และผู้ที่เสนอราคาได้ ผู้ขายต้องใส่สคริปต์ที่ประเมินคะแนนการเสนอราคาแต่ละรายการด้วย scoreAd()
  3. โค้ดของผู้ซื้อที่ได้รับเชิญจะทำงานเพื่อสร้างราคาเสนอ, URL สําหรับครีเอทีฟโฆษณาที่เกี่ยวข้อง และข้อมูลอื่นๆ สคริปต์การเสนอราคาสามารถค้นหาข้อมูลแบบเรียลไทม์ เช่น งบประมาณแคมเปญโฆษณาที่เหลือ ได้จากบริการคีย์/ค่าของผู้ซื้อ
  4. โค้ดของผู้ขายจะประเมินราคาเสนอแต่ละรายการและเลือกผู้ชนะ ตรรกะนี้ใช้ค่าราคาเสนอและข้อมูลอื่นๆ เพื่อแสดงผลความน่าดึงดูดใจของราคาเสนอ ระบบจะปฏิเสธโฆษณาที่ไม่สามารถเอาชนะโฆษณาตามบริบทที่มีประสิทธิภาพสูงสุด ผู้ขายสามารถใช้บริการคีย์/ค่าของตนเองสำหรับข้อมูลแบบเรียลไทม์
  5. ระบบจะแสดงโฆษณาที่ชนะเป็นค่าทึบ ซึ่งจะแสดงในเฟรมที่มีขอบ ทั้งผู้ขายและผู้เผยแพร่โฆษณาจะดูค่านี้ไม่ได้
  6. ระบบจะรายงานการประมูลให้ผู้ขายและผู้ซื้อที่ชนะทราบ

การประมูลจะจัดขึ้นเมื่อใด

Protected Audience API สามารถทํางานได้ด้วยตัวเองหรือร่วมกับการประมูลแบบเป็นโปรแกรม ในการประมูลแบบเป็นโปรแกรมซึ่งมีผู้ขายหลายราย

  1. ผู้ใช้เข้าชมเว็บไซต์ที่เข้าร่วม
  2. ผู้ขายรายอื่นเป็นผู้ดำเนินการประมูลแบบเป็นโปรแกรมเพื่อค้นหาโฆษณาตามบริบทสำหรับช่องโฆษณาที่พร้อมใช้งาน
  3. การประมูล Protected Audience API จะเริ่มขึ้น
  4. scoreAd()เปรียบเทียบราคาเสนอของผู้ซื้อกับผลการประมูลครั้งแรก

ระบบจะปฏิเสธราคาเสนอที่ไม่สามารถเอาชนะผู้ชนะตามบริบท

ใครเป็นผู้ดำเนินการประมูลโฆษณา Protected Audience API

มีบุคคลหลายฝ่ายที่อาจทำการประมูลเพื่อขายพื้นที่โฆษณา

เช่น

  • ผู้เผยแพร่เนื้อหา: ดำเนินการในนามของตนเองเพื่อโฮสต์เนื้อหาโฆษณาในเว็บไซต์
  • แพลตฟอร์มฝั่งขาย (SSP): ทำงานร่วมกับผู้เผยแพร่โฆษณาและให้บริการอื่นๆ
  • สคริปต์ของบุคคลที่สาม: ทํางานในนามของผู้เผยแพร่โฆษณาเพื่อให้เข้าร่วมการประมูลโฆษณาได้

เมื่อใช้ Protected Audience API ผู้ขายมีหน้าที่ 3 อย่างดังนี้

  • บังคับใช้กฎของผู้เผยแพร่โฆษณา: ผู้ซื้อและราคาเสนอที่มีสิทธิ์
  • เรียกใช้ตรรกะการประมูล: JavaScript ทำงานใน Worklet เพื่อคํานวณคะแนนความน่าพึงพอใจสําหรับราคาเสนอแต่ละรายการ
  • รายงานผลการประมูล

งานเหล่านี้จะทําแบบเป็นโปรแกรมในโค้ดที่ผู้ขายระบุเมื่อเริ่มการประมูลโฆษณาโดยการเรียกใช้ฟังก์ชัน JavaScript navigator.runAdAuction()

ฟังก์ชัน API

runAdAuction()

ผู้ขายส่งคําขอไปยังเบราว์เซอร์ของผู้ใช้เพื่อเริ่มการประมูลโฆษณาโดยการเรียกใช้ navigator.runAdAuction()

เช่น

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() จะแสดงผลลัพธ์เป็น URN (urn:uuid:<something>) ที่แสดงถึงผลลัพธ์ของการประมูลโฆษณา เบราว์เซอร์จะถอดรหัสได้ก็ต่อเมื่อส่งไปยังเฟรมที่มีการป้องกันเพื่อการแสดงผลเท่านั้น หน้าผู้เผยแพร่โฆษณาจะตรวจสอบโฆษณาที่ชนะไม่ได้

สคริปต์ decisionLogicUrl จะพิจารณาโฆษณาแต่ละรายการ รวมถึงราคาเสนอและข้อมูลเมตาที่เกี่ยวข้องทีละรายการ จากนั้นจึงกําหนดคะแนนความน่าพึงพอใจเป็นตัวเลข

ที่พัก auctionConfig แห่ง

seller
ต้องระบุ
ตัวอย่าง: 'https://ssp.example'
บทบาท: ต้นทางของผู้ขาย
decisionLogicUrl
ต้องระบุ
ตัวอย่าง: 'https://ssp.example/auction-decision-logic.js'
บทบาท: URL สําหรับ JavaScript ของเวิร์กเลตการประมูล
trustedScoringSignalsUrl
ไม่บังคับ
ตัวอย่าง: 'https://ssp.example/scoring-signals'
บทบาท: URL ของเซิร์ฟเวอร์ที่เชื่อถือได้ของผู้ขาย
interestGroupBuyers
ต้องระบุ
ตัวอย่าง: ['https://dsp.example', 'https://buyer2.example', ...]
บทบาท: ต้นทางของเจ้าของกลุ่มความสนใจทั้งหมดที่ขอให้เสนอราคาในการประมูล
หมายเหตุ: ผู้ขายอาจระบุ interestGroupBuyers: เพื่ออนุญาตให้กลุ่มความสนใจทั้งหมดเสนอราคาได้ จากนั้นระบบจะยอมรับหรือปฏิเสธโฆษณาตามเกณฑ์อื่นๆ นอกเหนือจากการรวมเจ้าของกลุ่มความสนใจ ตัวอย่างเช่น ผู้ขายอาจตรวจสอบครีเอทีฟโฆษณาเพื่อยืนยันว่าเป็นไปตามนโยบาย
auctionSignals
ไม่บังคับ
ตัวอย่าง: {...}
บทบาท: ข้อมูลผู้ขายเกี่ยวกับบริบทหน้าเว็บ ประเภทการประมูล ฯลฯ
sellerSignals
ไม่บังคับ
ตัวอย่าง: {...}
บทบาท: ข้อมูลตามการตั้งค่าของผู้เผยแพร่โฆษณา การสร้างคําขอโฆษณาตามบริบท ฯลฯ
sellerTimeout
ไม่บังคับ
ตัวอย่าง: 100
บทบาท: รันไทม์สูงสุด (ms) ของสคริปต์ scoreAd() ของผู้ขาย
perBuyerSignals
ไม่บังคับ
ตัวอย่าง 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
บทบาท: สัญญาณตามบริบทเกี่ยวกับหน้าเว็บสําหรับผู้ซื้อแต่ละรายจากเซิร์ฟเวอร์ของผู้ซื้อ
perBuyerTimeouts
ไม่บังคับ
ตัวอย่าง: 50
บทบาท: รันไทม์สูงสุด (ms) ของสคริปต์ generateBid() ของผู้ซื้อรายใดรายหนึ่ง
componentAuctions
ไม่บังคับ
ตัวอย่าง 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
บทบาท: การกําหนดค่าเพิ่มเติมสําหรับการประมูลคอมโพเนนต์

decisionLogicUrl

decisionLogicUrl เป็นพร็อพเพอร์ตี้ของออบเจ็กต์การกําหนดค่าการประมูลซึ่งส่งไปยัง runAdAuction() URL นี้ต้องมีสคริปต์สําหรับฟังก์ชัน scoreAd() ระบบจะเรียกใช้ตรรกะนี้ 1 ครั้งสําหรับโฆษณาแต่ละรายการเพื่อพิจารณาความน่าพึงพอใจ

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals คือออบเจ็กต์ที่เบราว์เซอร์สร้างขึ้น ซึ่งประกอบด้วยข้อมูลที่เบราว์เซอร์ทราบและสคริปต์การประมูลของผู้ขายอาจต้องการยืนยัน

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

ก่อนที่การประมูลจะเริ่มขึ้น ผู้ขายจะค้นหาโฆษณาตามบริบทที่ดีที่สุดสําหรับช่องโฆษณาที่พร้อมใช้งาน ตรรกะ scoreAd() ส่วนหนึ่งจะปฏิเสธโฆษณาที่ไม่สามารถเอาชนะผู้ชนะตามบริบท

scoreAd()

scoreAd() ใช้อาร์กิวเมนต์ต่อไปนี้

อาร์กิวเมนต์ บทบาท
adMetadata ข้อมูลเมตาที่กำหนดโดยผู้ซื้อ
auctionConfig ออบเจ็กต์การกําหนดค่าการประมูลที่ส่งไปยัง navigator.runAdAuction()
bid ค่าราคาเสนอที่เป็นตัวเลข
trustedScoringSignals ค่าที่ดึงข้อมูล ณ เวลาประมูลจากเซิร์ฟเวอร์ที่เชื่อถือได้ของผู้ขาย ซึ่งแสดงความคิดเห็นของผู้ขายเกี่ยวกับโฆษณา

คำถามที่พบบ่อย

มีการตัดสินผู้ชนะการประมูลอย่างไรและใครเป็นผู้เลือก

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

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

การอ้างอิง Protected Audience API ทั้งหมด

มีคู่มืออ้างอิง API ดังต่อไปนี้

ตัวอธิบาย Protected Audience API ยังให้รายละเอียดเกี่ยวกับการรองรับและข้อจำกัดต่างๆ ของฟีเจอร์ด้วย