ตั้งค่าการประมูลเพื่อแสดงโฆษณาในหน้าของผู้เผยแพร่โฆษณา

ดูวิธีกำหนดค่าการประมูล Protected Audience API

การประมูลในอุปกรณ์ที่ผู้ขายเรียกใช้

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

  1. ผู้ขายเป็นผู้ตัดสินใจว่า (ก) ผู้ซื้อรายใดสามารถเข้าร่วมได้ และ (ข) ราคาเสนอใดจากกลุ่มความสนใจของผู้ซื้อเหล่านั้นมีสิทธิ์เข้าสู่การประมูล วิธีนี้ช่วยให้ผู้ขายบังคับใช้กฎของเว็บไซต์สำหรับโฆษณาที่ได้รับอนุญาตให้ปรากฏบนหน้าเว็บ
  2. ผู้ขายเป็นผู้รับผิดชอบในตรรกะทางธุรกิจของการประมูล นั่นคือ โค้ด JavaScript ที่จะพิจารณาราคาและข้อมูลเมตาของราคาเสนอแต่ละรายการ และคำนวณคะแนน "ความพึงประสงค์" ราคาเสนอที่มีคะแนนความต้องการสูงสุดจะชนะการประมูล
  3. ผู้ขายจะรายงานผลการประมูล ซึ่งรวมถึงข้อมูลเกี่ยวกับการล้างราคาและการชำระคืนอื่นๆ ผู้ซื้อที่ชนะและแพ้ก็ยัง ทำรายงานของตัวเองด้วย

เอกสารนี้จะอธิบายวิธีกำหนดค่าและเริ่มต้นการประมูลในอุปกรณ์

กำหนดค่าการประมูลเพื่อแสดงโฆษณา Protected Audience API

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

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 แห่ง

พร็อพเพอร์ตี้ที่จำเป็น

พร็อพเพอร์ตี้เดียวที่จำเป็นสำหรับ auctionConfigs คือ seller, decisionLogicUrl และ interestGroupBuyers

พร็อพเพอร์ตี้ ตัวอย่าง บทบาท
seller https://seller.example ต้นทางของผู้ขาย
decisionLogicUrl https://seller.example/decision-logic.js URL สำหรับเวิร์กเล็ตตรรกะการตัดสินใจของ JavaScript ในการประมูล ช่องนี้ต้องมีต้นทางเหมือนกับช่องผู้ขาย
interestGroupBuyers [https://buyer-1.example,
https://buyer-2.example,
...]		 ต้นทางของเจ้าของกลุ่มความสนใจทุกรายที่ขอเสนอราคาในการประมูล

พร็อพเพอร์ตี้ที่ไม่บังคับ

พร็อพเพอร์ตี้ที่เหลือสำหรับ auctionConfigs เป็นพร็อพเพอร์ตี้ที่ไม่บังคับ

พร็อพเพอร์ตี้ ตัวอย่าง บทบาท
trustedScoringSignalsUrl https://seller.example/scoring-signals URL ของเซิร์ฟเวอร์คีย์/ค่าของผู้ขาย ซึ่งจะค้นหาระหว่างขั้นตอนการให้คะแนนโฆษณาโดยใช้ URL การแสดงผลของครีเอทีฟโฆษณาเป็นคีย์ ช่องนี้ต้องมีต้นทางเหมือนกับช่องผู้ขาย
auctionSignals {"หมวดหมู่":"ข่าว"} ออบเจ็กต์ที่ต่อเนื่องได้ในรูปแบบ JSON ซึ่งแสดงสัญญาณที่ผู้ซื้อและผู้ขายทุกรายเข้าร่วมการประมูลได้
sellerSignals {...} ออบเจ็กต์ที่ต่อเนื่องได้ของ JSON ซึ่งแสดงสัญญาณที่มีให้แก่ผู้ขายเท่านั้น
perBuyerSignals {https://dsp.example: {...},
https://another-buyer.example: {...},
... }		 สัญญาณที่พร้อมให้บริการแก่ผู้ซื้อที่เฉพาะเจาะจง สัญญาณอาจมาจากผู้ขายและผู้ซื้อเอง
perBuyerTimeouts {https://www.example-dsp.com: 50,
https://www.another-buyer.com: 200,
*: 150,
...},		 รันไทม์สูงสุดเป็นมิลลิวินาทีของสคริปต์ generateBid() ของผู้ซื้อที่เฉพาะเจาะจง สัญลักษณ์ไวลด์การ์ดจะใช้กับผู้ซื้อทุกรายที่ไม่มีการระบุระยะหมดเวลาที่เฉพาะเจาะจง
sellerTimeout 100 รันไทม์สูงสุดเป็นมิลลิวินาทีของสคริปต์ ScoreAd() ของผู้ขาย
componentAuctions [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] การกำหนดค่าเพิ่มเติมสำหรับการประมูลแบบผสม
resolveToConfig จริง|เท็จ บูลีนที่กำหนดสัญญาที่แสดงผลจาก runAdAuction() ให้มีการแปลงไปที่ FencedFrameConfig หากเป็น true (สำหรับใช้ใน <fencedframe>) หรือไปยัง URL urn:uuid ที่ทึบหากเป็น false (สำหรับใช้ใน <iframe>) ค่าเริ่มต้นคือ false

ระบุสัญญาณแบบไม่พร้อมกัน

ค่าของสัญญาณบางอย่าง (ซึ่งกำหนดค่าโดยช่อง auctionSignals, sellerSignals, perBuyerSignals และ perBuyerTimeouts) อาจไม่จำเป็นต้องระบุค่าที่เป็นรูปธรรม แต่ใช้เป็นคำสัญญา ซึ่งทำให้บางส่วนของการประมูล เช่น การโหลดสคริปต์และสัญญาณที่เชื่อถือได้ และการเปิดตัวกระบวนการ Worklet ที่แยกออกมาได้ ให้ทับซ้อนกับการคำนวณ (หรือการดึงข้อมูลเครือข่าย) ของค่าเหล่านั้น สคริปต์ Worklet จะเห็นเฉพาะค่าที่ได้รับการแก้ไขเท่านั้น หากมีการปฏิเสธคำสัญญาดังกล่าว การประมูลจะถูกล้มเลิกเว้นแต่จะมีการจัดการไม่สำเร็จแล้วหรือมีการล้มเลิกในรูปแบบอื่นๆ

กำหนดค่าการประมูลกับผู้ขายหลายราย

ในบางกรณี ผู้ขายหลายรายอาจต้องการเข้าร่วมการประมูล โดยผู้ที่ชนะในการประมูลแยกกันจะถูกนำไปไปสู่การประมูลอื่น ซึ่งผู้ขายอีกรายหนึ่งเป็นผู้เรียกใช้ การประมูลที่ผ่านช่วงเหล่านี้นี้เรียกว่าการประมูลแบบคอมโพเนนต์ ออบเจ็กต์ componentAuctions อาจมีการกำหนดค่าการประมูลเพิ่มเติมสำหรับการประมูลคอมโพเนนต์ของผู้ขายแต่ละรายได้ เพื่ออำนวยความสะดวกการประมูลองค์ประกอบเหล่านี้ ราคาเสนอที่ชนะของการประมูลส่วนประกอบเหล่านี้แต่ละครั้งจะเข้าสู่การประมูล "ระดับบนสุด" ซึ่งเป็นการตัดสินใจขั้นสุดท้ายของการประมูล auctionConfig ของการประมูลคอมโพเนนต์อาจไม่มี componentAuctions เป็นของตัวเอง เมื่อ componentAuctions ไม่ว่างเปล่า interestGroupBuyers ต้องว่างเปล่า กล่าวคือ ในการประมูลกลุ่มเป้าหมายที่ได้รับการคุ้มครองหนึ่งๆ จะมีผู้ขายรายเดียวและไม่มีการประมูลที่เป็นส่วนประกอบ หรือราคาเสนอทั้งหมดมาจากการประมูลที่เป็นส่วนประกอบ และการประมูลระดับบนสุดจะเลือกได้เฉพาะผู้ชนะของการประมูลที่เป็นส่วนประกอบเท่านั้น

เรียกใช้การประมูล

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

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

การเรียก runAdAuction() จะส่งคืนคำสัญญาที่แสดงถึงโฆษณา โค้ดใดๆ ในหน้าของผู้เผยแพร่โฆษณาไม่สามารถตรวจสอบโฆษณาที่ชนะการประมูล หรือเรียนรู้เกี่ยวกับเนื้อหาของโฆษณานั้นจากผลลัพธ์ของ runAdAuction() หากตั้งค่าแฟล็ก resolveToConfig เป็น "จริง" ใน AuctionConfig ระบบจะแสดงผลออบเจ็กต์ FencedFrameConfig ซึ่งแสดงผลได้ในเฟรมที่มีการปิดกั้นเท่านั้น หากตั้งค่าแฟล็กเป็น "เท็จ" ระบบจะส่ง URN ทึบแสงกลับมาที่แสดงผลใน iframe ได้ อาจเป็นไปได้ที่ runAdAuction จะแสดงค่า Null ซึ่งแสดงว่าไม่ได้เลือกโฆษณาไว้ ในกรณีนี้ ผู้ขายอาจเลือกที่จะ แสดงผลโฆษณาที่กำหนดเป้าหมายตามบริบท