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

คู่มือและข้อมูลอ้างอิง 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 ที่แยกต่างหากซึ่งไม่สามารถสื่อสารกับโลกภายนอกได้

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 ที่ทำงานในเวิร์กเล็ตเพื่อคำนวณคะแนนความน่าสนใจสำหรับราคาเสนอแต่ละรายการ
• รายงานผลการประมูล

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

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

ที่พัก auctionConfig แห่ง

seller

ต้องระบุ

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

บทบาท: ต้นทางของผู้ขาย

decisionLogicUrl

ต้องระบุ

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

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

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() ระบบจะเรียกใช้ตรรกะนี้ 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() รับอาร์กิวเมนต์ต่อไปนี้

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

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

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

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

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

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

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

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