คู่มือและข้อมูลอ้างอิงเกี่ยวกับ Seller API สำหรับการประมูลเพื่อแสดงโฆษณา Protected Audience API
ในบทความนี้ คุณจะพบกับข้อมูลอ้างอิงทางเทคนิคสำหรับการประมูลเพื่อแสดงโฆษณา ดังที่ใช้ในการทำซ้ำปัจจุบันของ Protected Audience API เวอร์ชันทดลอง
อ่านคู่มือนักพัฒนาซอฟต์แวร์เพื่อดู Protected Audience API ตลอดอายุการใช้งาน และดูคำอธิบายโดยละเอียดเกี่ยวกับวิธีที่ผู้ขายเรียกใช้การประมูลในอุปกรณ์ได้จากคำอธิบายโดยละเอียดของ Protected Audience API
หากคุณไม่ใช่นักพัฒนาซอฟต์แวร์ ดูภาพรวมของ Protected Audience API
การประมูลเพื่อแสดงโฆษณา Protected Audience API คืออะไร
การประมูลเพื่อแสดงโฆษณา Protected Audience API คือชุดโปรแกรม JavaScript ขนาดเล็กที่เบราว์เซอร์ทำงานในอุปกรณ์ของผู้ใช้เพื่อเลือกโฆษณา เพื่อรักษาความเป็นส่วนตัว โค้ดการประมูลเพื่อแสดงโฆษณาทั้งหมดจากผู้ขายและผู้ซื้อจะทำงานในเวิร์กเล็ต JavaScript ที่แยกออกมาต่างหากที่ไม่สามารถพูดคุยกับภายนอก
- ผู้ใช้เข้าชมเว็บไซต์ที่แสดงโฆษณา
- โค้ดของผู้ขายจะทำงาน
navigator.runAdAuction()
ซึ่งจะระบุว่าพื้นที่โฆษณาใดสำหรับขายและใครเสนอราคาได้ ผู้ขายต้องรวมสคริปต์ ที่ระบุคะแนนการเสนอราคาแต่ละครั้งไว้ด้วยscoreAd()
- โค้ดของผู้ซื้อที่ได้รับเชิญจะดำเนินการสร้างราคาเสนอ, URL สำหรับครีเอทีฟโฆษณาที่เกี่ยวข้อง และข้อมูลอื่นๆ สคริปต์การเสนอราคาสามารถสืบค้นข้อมูลแบบเรียลไทม์ เช่น งบประมาณแคมเปญโฆษณาที่เหลือ จากบริการจัดการคีย์/ค่าของผู้ซื้อได้
- โค้ดของผู้ขายจะให้คะแนนราคาเสนอแต่ละรายการและเลือกผู้ชนะ ตรรกะนี้ใช้ค่าราคาเสนอและข้อมูลอื่นๆ จะแสดงราคาเสนอที่ต้องการ โฆษณาที่ไม่สามารถเอาชนะโฆษณาที่ชนะตามบริบทจะถูกปฏิเสธ ผู้ขายสามารถใช้บริการจัดการคีย์/ค่าของตนเองสำหรับข้อมูลแบบเรียลไทม์
- ส่วนโฆษณาที่ชนะจะแสดงเป็นค่าทึบแสง ซึ่งจะแสดงในเฟรมที่มีการปิดกั้น ทั้งผู้ขายและผู้เผยแพร่โฆษณา จะไม่เห็นค่านี้
- การประมูลจะรายงานไปยังผู้ขายและผู้ซื้อที่ชนะ
การประมูลจะมีขึ้นเมื่อใด
โดยจะเรียกใช้ Protected Audience API ด้วยตนเองหรือกับการประมูลแบบเป็นโปรแกรมก็ได้ ในการประมูลแบบเป็นโปรแกรม ที่มีผู้ขายหลายราย
- ผู้ใช้เข้าชมเว็บไซต์ที่เข้าร่วม
- ผู้ขายรายอื่นจะเรียกใช้การประมูลแบบเป็นโปรแกรมเพื่อค้นหาโฆษณาตามบริบทสำหรับช่องโฆษณาที่พร้อมให้บริการ
- การประมูล Protected Audience API ทํางานอยู่
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>
) ซึ่งแสดงผลการประมูลเพื่อแสดงโฆษณา ซึ่งจะถอดรหัสได้โดยเบราว์เซอร์เมื่อส่งไปยังเฟรมที่มีการปิดกั้นเพื่อการแสดงผลเท่านั้น กล่าวคือ หน้าของผู้เผยแพร่โฆษณาจะตรวจสอบโฆษณาที่ชนะไม่ได้
สคริปต์ 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()
รับอาร์กิวเมนต์ต่อไปนี้
อาร์กิวเมนต์ | บทบาท |
---|---|
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 ยังให้รายละเอียดเกี่ยวกับการรองรับและข้อจำกัดต่างๆ ของฟีเจอร์ด้วย