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

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

อัปเดต: FLEDGE เปลี่ยนชื่อเป็น Protected Audience API แล้ว หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการเปลี่ยนชื่อ โปรดดูที่บล็อกโพสต์

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

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

หากคุณไม่ใช่นักพัฒนาซอฟต์แวร์ โปรดดูภาพรวม Protected Audience API

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

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

แผนภาพนี้แสดงแต่ละขั้นตอนของการประมูลเพื่อแสดงโฆษณา Protected Audience API

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

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

คุณจะใช้ Protected Audience API ต่อได้ด้วยตัวเองหรือร่วมกับการประมูลแบบเป็นโปรแกรม ในผู้ขายหลายราย การประมูลแบบเป็นโปรแกรม

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

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

ใครเป็นผู้เรียกใช้การประมูลเพื่อแสดงโฆษณา Protected Audience API

มีหลายผู้ที่อาจใช้การประมูลเพื่อขายพื้นที่โฆษณา

เช่น

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

เมื่อใช้ Protected Audience API ผู้ขายมี 3 หน้าที่ต่อไปนี้

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

งานเหล่านี้ดำเนินการแบบเป็นโปรแกรมในโค้ดที่ผู้ขายให้ไว้เมื่อ ทำให้เกิดการประมูลเพื่อแสดงโฆษณาโดยการเรียกใช้ฟังก์ชัน 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>) ที่แสดงถึง ผลการประมูลเพื่อแสดงโฆษณา เบราว์เซอร์จะถอดรหัสได้เฉพาะเมื่อส่งผ่านไปยังเฟรมที่มีการปิดกั้น สำหรับการแสดงผล: หน้าเว็บของผู้เผยแพร่โฆษณาไม่สามารถตรวจสอบโฆษณาที่ชนะ

หมายเหตุ: ต้นทางของสคริปต์ที่มี joinAdInterestGroup() ต้องตรงกับต้นทางของเจ้าของกลุ่มความสนใจ ดังนั้น joinAdInterestGroup() จะ จำเป็นต้องเรียกใช้จาก iframe (ตัวอย่างเช่น จาก DSP) เว้นแต่ต้นทางของ เจ้าของกลุ่มความสนใจตรงกับ ต้นฉบับของเอกสารปัจจุบัน (สำหรับ เช่น เว็บไซต์ที่มีกลุ่มความสนใจเป็นของตนเอง) runAdAuction ไม่เหมือนกัน ดังนั้นการใช้แท็ก <script> จึงอาจมีประสิทธิภาพมากกว่า iframe แบบข้ามต้นทาง

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

ที่พัก auctionConfig แห่ง

หมายเหตุ: การใช้งาน Protected Audience API ปัจจุบันไม่รองรับ additionalBids อ่านการประมูล ผู้เข้าร่วมในส่วน ดูข้อมูลเพิ่มเติมเกี่ยวกับคำอธิบายสำหรับ Protected Audience API

seller

ต้องระบุ

ตัวอย่าง: 'https://ssp.example'

บทบาท: ต้นกำเนิดของผู้ขาย

decisionLogicUrl

ต้องระบุ

ตัวอย่าง: 'https://ssp.example/auction-decision-logic.js'

บทบาท: URL ของ Worklet JavaScript สำหรับการประมูล

trustedScoringSignalsUrl

ไม่บังคับ

ตัวอย่าง: 'https://ssp.example/scoring-signals'

บทบาท: URL ของเซิร์ฟเวอร์ที่เชื่อถือได้ของผู้ขาย

interestGroupBuyers

ต้องระบุ

ตัวอย่าง: ['https://dsp.example', 'https://buyer2.example', ...]

บทบาท: ต้นทางที่เจ้าของกลุ่มความสนใจทั้งหมดขอเสนอราคาในการประมูล

หมายเหตุ: ผู้ขายอาจระบุ interestGroupBuyers: เพื่ออนุญาตให้กลุ่มความสนใจทั้งหมดเสนอราคาได้ จากนั้น ระบบจะยอมรับหรือปฏิเสธโฆษณาตามเกณฑ์อื่นนอกเหนือจากการรวมเจ้าของกลุ่มความสนใจ ตัวอย่างเช่น ผู้ขายอาจตรวจสอบครีเอทีฟโฆษณาเพื่อยืนยันว่าปฏิบัติตามนโยบายของตน

auctionSignals

ไม่บังคับ

ตัวอย่าง: {...}

บทบาท: ข้อมูลผู้ขายเกี่ยวกับบริบทในหน้าเว็บ ประเภทการประมูล ฯลฯ

sellerSignals

ไม่บังคับ

ตัวอย่าง: {...}

บทบาท: ข้อมูลตามการตั้งค่าของผู้เผยแพร่โฆษณา การสร้างคำขอโฆษณาตามบริบท ฯลฯ

sellerTimeout

ไม่บังคับ

ตัวอย่าง: 100

บทบาท: รันไทม์สูงสุด (มิลลิวินาที) ของสคริปต์ scoreAd() ของผู้ขาย

perBuyerSignals

ไม่บังคับ

ตัวอย่าง:

{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }

บทบาท: สัญญาณบริบทเกี่ยวกับหน้าเว็บสำหรับผู้ซื้อแต่ละรายจากเซิร์ฟเวอร์ของผู้ซื้อ

perBuyerTimeouts

ไม่บังคับ

ตัวอย่าง: 50

บทบาท: รันไทม์สูงสุด (มิลลิวินาที) ของสคริปต์ generateBid() ของผู้ซื้อบางราย

componentAuctions

ไม่บังคับ

ตัวอย่าง:

[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]

บทบาท: การกำหนดค่าเพิ่มเติมสำหรับการประมูลคอมโพเนนต์

decisionLogicUrl

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

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
• คู่มือผู้ซื้อโฆษณาสําหรับกลุ่มความสนใจและการสร้างราคาเสนอของ Protected Audience
• คู่มือสำหรับผู้ขายโฆษณาเกี่ยวกับการประมูลเพื่อแสดงโฆษณาใน Protected Audience
• คู่มือการรายงานผลการประมูล
• แนวทางปฏิบัติแนะนำสำหรับ Protected Audience เวลาในการตอบสนองในการประมูลเพื่อแสดงโฆษณา
• แก้ปัญหา Protected Audience

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