การรายงานการประมูลของ Protected Audience API

วัดข้อมูลและผลลัพธ์ของการประมูล Protected Audience API

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

Protected Audience API จะทำงานกับสิ่งต่อไปนี้ เพื่อรายงานเกี่ยวกับเมตริกสำคัญที่รวบรวมจากการประมูลเพื่อแสดงโฆษณา

• การรวมข้อมูลแบบส่วนตัวซึ่งรวบรวมสัญญาณและผลลัพธ์ของการประมูลเพื่อสร้างรายงานสรุป
• Ads Reporting API สําหรับ Fenced Frame และ iframe ซึ่งเป็นแชแนลภายในเฟรมเพื่อสื่อสารกับเวิร์กเล็ต Protected Audience API API ช่วยให้เชื่อมโยงข้อมูลระดับเหตุการณ์กับสัญญาณการประมูลได้ การรายงานระดับเหตุการณ์ของ Ads Reporting API เป็นกลไกการเปลี่ยนผ่านจนกว่าจะมีการออกแบบกลไกการรายงานที่มีความเป็นส่วนตัวมากขึ้น
• Attribution Reporting ที่ช่วยให้คุณเชื่อมโยงข้อมูล Conversion กับสัญญาณการประมูลได้
• พื้นที่เก็บข้อมูลที่ใช้ร่วมกัน ซึ่งให้คุณเขียนสัญญาณการประมูลไปยังพื้นที่เก็บข้อมูลแบบข้ามต้นทาง แล้วให้คุณรายงานข้อมูลดังกล่าวในภายหลังได้โดยใช้การรวบรวมข้อมูลส่วนตัว

ภาพรวมการรายงานของ Protected Audience API

วันที่

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

ในระหว่างการประมูล คุณสามารถรายงานข้อมูลการประมูลได้โดยใช้ชิ้นงานการรายงาน ในระหว่างการแสดงภาพ คุณรายงานข้อมูลการมีส่วนร่วมจาก iframe หรือเฟรมที่มีการปิดกั้นได้ ในระหว่างเวลาที่เกิด Conversion คุณรายงานข้อมูลการระบุแหล่งที่มาจากหน้าปลายทางได้โดยใช้ Attribution Reporting API

ตำแหน่งการรายงาน

ในการประมูล ผู้ซื้อจะรายงานสัญญาณที่มีอยู่ในเวิร์กโฟลว์ generateBid() และ reportWin() ได้ และผู้ขายจะรายงานสัญญาณที่มีอยู่ใน scoreAd() และ reportResult() ได้ นอกเหนือจากการประมูล ผู้ซื้อและผู้ขายสามารถรายงานข้อมูลจากเฟรมที่แสดงโฆษณาและจากเว็บไซต์ที่ทำให้เกิด Conversion ได้

ในแต่ละระยะเวลาที่แสดง ผู้ซื้อและผู้ขายจะมีสิทธิ์เข้าถึง API การรายงานต่างๆ ที่พร้อมให้ใช้งานเพื่อรายงานข้อมูล เช่น สัญญาณการประมูล ข้อมูลระดับเหตุการณ์ และข้อมูล Conversion

ข้อมูลที่มีในการประมูล Protected Audience API

ข้อมูลต่อไปนี้พร้อมให้รายงานจากเวิร์กเล็ต Protected Audience API ระหว่างการประมูล

สัญญาณ

สัญญาณคือข้อมูลบริบทของการประมูล ข้อมูลผู้ใช้ ข้อมูลแบบเรียลไทม์ และข้อมูลเบราว์เซอร์ที่ผู้ซื้อและผู้ขายเข้าถึงได้ภายในพื้นที่ทำงานเพื่อสร้างราคาเสนอ ให้คะแนนโฆษณา และรายงานผลการประมูล

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

ข้อมูลอื่นๆ ที่มี

• ข้อมูลผลลัพธ์ที่เกี่ยวข้องกับข้อมูลการชนะและแพ้การประมูล เช่น ราคาเสนอที่ชนะและเหตุผลการปฏิเสธราคาเสนอ
• ข้อมูลประสิทธิภาพที่มีข้อมูลเวลาในการตอบสนอง เช่น ระยะเวลาที่ใช้ในการดึงข้อมูลและเรียกใช้เวิร์กเล็ตการเสนอราคา

ข้อมูลที่พร้อมใช้งานนอกการประมูล Protected Audience API

นอกการประมูล Protected Audience API จะมีระยะเวลา 2 ช่วงที่สามารถรายงานข้อมูลได้

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

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

การรายงานระดับเหตุการณ์

รายงานระดับเหตุการณ์แสดงรายละเอียดจากเหตุการณ์อย่างน้อย 1 เหตุการณ์ เหตุการณ์อาจเป็นการชนะการประมูล การแสดงโฆษณา หรือ Conversion จนถึงปี 2026 เป็นอย่างน้อย การรายงานการชนะการประมูลระดับเหตุการณ์จะยังคงอยู่ ไม่จำเป็นต้องใช้เฟรมที่มีการปิดกั้นเพื่อแสดงโฆษณา Protected Audience และ iframe ที่มีสิทธิ์เข้าถึงเครือข่ายแบบไม่จำกัดสามารถใช้สำหรับการรายงานระดับเหตุการณ์ได้ นอกจากนี้ Ads Reporting API ยังใช้ได้ในเฟรมและ iframe ที่มีการปิดกั้นเพื่อให้คุณเชื่อมโยงข้อมูลการประมูลและ Conversion กับข้อมูลระดับเหตุการณ์จากเฟรมได้ด้วย ซึ่งออกแบบมาเพื่อให้ระบบนิเวศมีเส้นทางในการย้ายข้อมูลที่ง่ายขึ้น เนื่องจากคุณจะใช้โครงสร้างพื้นฐานการรายงานที่มีอยู่ต่อไปได้จนถึงวันที่ 2026 เป็นอย่างน้อยในขณะที่ย้ายข้อมูลระบบไปยัง Protected Audience

การรายงานการชนะการประมูลระดับเหตุการณ์ด้วย sendReportTo()

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

ตัวอย่างเช่น ผู้ซื้อสามารถรายงานราคาเสนอที่ชนะจาก Worklet reportWin() เพื่อวัตถุประสงค์ในการเรียกเก็บเงินได้

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

คุณใช้ฟังก์ชัน sendReportTo() เพื่อสร้างรายงานชนะใจผู้ขายเมื่อโทรจาก reportResult() และรายงานผู้ชนะสำหรับผู้ซื้อเมื่อเรียกใช้จาก reportWin() ได้ ฟังก์ชัน sendReportTo() ใช้ได้จนถึง 2026 เป็นอย่างน้อย

รายงานการมีส่วนร่วม

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

ฟังก์ชัน sendReportTo() ที่อธิบายข้างต้นสามารถใช้เพื่อเชื่อมโยงข้อมูลการประมูลกับข้อมูลระดับเหตุการณ์จาก iframe ได้ แต่จะใช้ไม่ได้สำหรับเฟรมที่มีการปิดกั้น เนื่องจากรหัสที่ไม่ซ้ำกันไม่สามารถส่งผ่านจากตัวฝังได้เนื่องจากการสื่อสารระหว่างเครื่องมือฝังกับเฟรม fenced มีจำกัด ใช้ Ads Reporting API สำหรับการเชื่อมโยงข้อมูลการประมูลกับข้อมูลระดับเหตุการณ์จากโฆษณาแบบเฟรมที่มีการปิดกั้น

Ads Reporting API สำหรับเฟรมและ iframe ที่มีการปิดกั้น

Ads Reporting API สําหรับเฟรมและ iframe ที่มีการปิดกั้นมีกลไกให้คุณเชื่อมโยงข้อมูลระดับเหตุการณ์ของผู้ใช้จากเฟรมโฆษณากับสัญญาณภายในการประมูลที่ใช้ Protected Audience API

ในเวิร์กเล็ตการรายงานของ Protected Audience API คุณสามารถลงทะเบียนบีคอนโฆษณาด้วยฟังก์ชัน registerAdBeacon() และส่งไปใน URL การรายงานที่มีการเพิ่มสัญญาณเป็นพารามิเตอร์การค้นหา นอกจากนี้ คุณยังระบุเหตุการณ์ที่กําหนดเองที่ต้องการเชื่อมโยงกับ URL การรายงานได้ด้วย จากนั้น เมื่อโฆษณาแสดงในเฟรมที่มีการปิดกั้น คุณจะทริกเกอร์เหตุการณ์ที่กำหนดเองได้โดยเรียกใช้ฟังก์ชัน window.fence.reportEvent() เพิ่มข้อมูลที่อยู่ในเฟรมที่มีการปิดกั้นเป็นเพย์โหลดได้

ฟังก์ชัน registerAdBeacon() ใช้ได้เฉพาะในฟังก์ชันการรายงานเท่านั้น และไม่พร้อมใช้งานในตรรกะการเสนอราคาของผู้ซื้อและตรรกะการให้คะแนนของผู้ขาย

ในตัวอย่างต่อไปนี้ รหัสแคมเปญเชื่อมโยงกับเพย์โหลดระดับเหตุการณ์ด้วยพิกัดการคลิก

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

นอกจากนี้ API การรายงานโฆษณา Fenced Frames จะยังใช้งานได้จนถึงปี 2026 เป็นอย่างน้อยด้วยเหตุผลเดียวกับการชนะการรายงาน

ดูข้อมูลแบบเจาะลึกได้ในคำอธิบาย

การเข้าถึงเครือข่ายที่ไม่จำกัด

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

ระบบจะจำกัดสิทธิ์เข้าถึงเครือข่ายในอนาคต

รายงานการระบุแหล่งที่มา

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

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

กลไกการเปลี่ยนรุ่น

เมื่อลงทะเบียนบีคอนโฆษณา คุณสามารถใช้คีย์เวิร์ด reserved.top_navigation ซึ่งจะเพิ่มส่วนหัว Attribution-Reporting-Eligible โดยอัตโนมัติเพื่อให้บีคอนมีสิทธิ์ลงทะเบียนเป็นแหล่งที่มาของการระบุแหล่งที่มา

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

หากต้องการแนบข้อมูลระดับเหตุการณ์กับบีคอนที่ลงทะเบียนไว้ คุณสามารถเรียกใช้ setReportEventDataForAutomaticBeacons() จากเฟรมที่มีการปิดกั้นด้วยเพย์โหลดเหตุการณ์

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

โปรดดูข้อมูลเพิ่มเติมในส่วน Attribution Reporting ในตัวอธิบาย Ads Reporting API

ตัวอย่างการรายงาน Conversion และการมีส่วนร่วม

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

ในเวิร์กโฟลว์นี้ ผู้ซื้อจะประสานงานกับผู้ขายเพื่อส่งรหัสที่ไม่ซ้ำกันเข้าร่วมการประมูล โดยในระหว่างการประมูล ผู้ซื้อจะส่งรหัสที่ไม่ซ้ำกันนี้พร้อมกับข้อมูลการประมูล ในระหว่างการแสดงผลและเวลา Conversion ระบบจะส่งข้อมูลจากเฟรมที่มีการปิดกั้นหรือ iframe ด้วยรหัสที่ไม่ซ้ำกันเดียวกัน จากนั้นจะใช้รหัสที่ไม่ซ้ำกันเพื่อเชื่อมโยงรายงานเหล่านี้เข้าด้วยกัน

ขั้นตอนการทำงาน:

1. ก่อนที่การประมูลจะเริ่มขึ้น ผู้ซื้อจะส่งรหัสที่ไม่ซ้ำกันให้กับผู้ขาย ซึ่งเป็นส่วนหนึ่งของการเสนอราคาตอบด้วยการเสนอราคาแบบเรียลไทม์ ("RTB") แบบเป็นโปรแกรม คุณตั้งรหัสเป็นตัวแปรได้ เช่น auctionId มีการส่งรหัสเป็น perBuyerSignals ใน auctionConfig และจะใช้ได้ในเวิร์กเล็ตของผู้ซื้อ
2. ในระหว่างเวลาประมูล ผู้ซื้อสามารถลงทะเบียนบีคอนโฆษณาเพื่อทริกเกอร์ในระหว่างเวลาในการแสดงโฆษณาและเวลาที่เกิด Conversion (registerAdBeacon())
   1. หากต้องการเชื่อมโยงสัญญาณการประมูลสำหรับเหตุการณ์เฟรมโฆษณา ให้ตั้งค่า auctionId เป็นพารามิเตอร์การค้นหาของ URL บีคอน
   2. หากต้องการเชื่อมโยงสัญญาณการประมูลสำหรับเหตุการณ์ Conversion ให้ตั้งค่า auctionId ใน URL บีคอน
3. ในระหว่างที่มีการแสดงโฆษณา ระบบสามารถเรียกใช้หรือปรับปรุงบีคอนที่ลงทะเบียนไว้ในระหว่างเวลาการประมูลโดยใช้ข้อมูลระดับเหตุการณ์
   1. ทริกเกอร์เหตุการณ์เฟรมด้วย reportEvent() และส่งข้อมูลระดับเหตุการณ์
   2. เพิ่มเพย์โหลดระดับเหตุการณ์ลงในบีคอนการระบุแหล่งที่มาด้วย setReportEventDataForAutomaticBeacons()
   3. ลงทะเบียนโฆษณากับ Attribution Reporting API โดยตอบกลับคำขอบีคอนด้วยส่วนหัว Attribution-Reporting-Register-Source
4. ในระหว่างเวลาที่เกิด Conversion คุณจะเรียกใช้แหล่งที่มาที่ลงทะเบียนไว้ในระหว่างเวลาการประมูลได้

หลังจากกระบวนการข้างต้น ผู้ซื้อจะมีรายงานการประมูล รายงานการมีส่วนร่วม และรายงาน Conversion ซึ่งทั้งหมดเชื่อมโยงกันด้วยคีย์เฉพาะเพียงคีย์เดียวที่ใช้เชื่อมโยงกันได้

เวิร์กโฟลว์ที่คล้ายกันจะมีผลกับผู้ขายหากผู้ขายต้องการเข้าถึงข้อมูลการระบุแหล่งที่มา และผู้ขายสามารถใช้รหัสที่ไม่ซ้ำกันเพื่อส่งให้กับ registerAdBeacon() ได้ด้วย จากเฟรม การเรียก reportEvent() มีพร็อพเพอร์ตี้ปลายทางที่สามารถใช้เพื่อส่งรายงานไปยังทั้งผู้ซื้อและผู้ขายได้ โปรดทราบว่าต้องมี SSP ในหน้า Landing Page ด้วยเพื่อให้ทริกเกอร์ระบุแหล่งที่มาว่ามาจากแหล่งที่มา

การรวมข้อมูล Protected Audience

Private Aggregation API คือกลไกที่ใช้ในการรายงานข้อมูล Protected Audience เพื่อสร้างรายงานสรุป ซึ่งเป็นรายงานแบบรวมที่มีสัญญาณรบกวนและรวบรวมไว้ในที่เก็บข้อมูล ที่เก็บข้อมูลจะแสดงด้วยคีย์การรวม และข้อมูลบางอย่างสามารถเข้ารหัสลงในคีย์ได้

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

ดูบทความการรวมแบบส่วนตัวสำหรับข้อมูลเพิ่มเติมเกี่ยวกับ API

การรวมสัญญาณการประมูล

คุณรวบรวมสัญญาณที่มีภายใน Worklet กับเซิร์ฟเวอร์ของคุณได้โดยใช้ Private Aggregation สำหรับการรวมสัญญาณ คุณสามารถใช้เมธอด privateAggregation.contributeToHistogram() ที่มีอยู่ในเวิร์กเล็ตการเสนอราคาของผู้ซื้อ, Worklet การให้คะแนนผู้ขาย และเวิร์กเล็ตการรายงานผู้ซื้อ/ผู้ขาย

ในตัวอย่างนี้ ราคาเสนอที่ชนะจะรวมอยู่ในที่เก็บข้อมูลของเจ้าของกลุ่มความสนใจ

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

นี่คือกลไกทั่วไปที่จะใช้เมื่อสัญญาณที่คุณต้องการรวบรวมไม่ได้เชื่อมโยงกับข้อมูลระดับเหตุการณ์ และไม่ได้ทริกเกอร์โดยเหตุการณ์นอกการประมูล ดูข้อมูลเพิ่มเติมเกี่ยวกับการรายงานสัญญาณการประมูลได้ในคําอธิบาย

การรวมสัญญาณการประมูลกับข้อมูลเหตุการณ์

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

หากต้องการรวมสัญญาณการประมูลตามเหตุการณ์ คุณสามารถใช้ privateAggregation.contributeToHistogramOnEvent(eventType, contribution) ซึ่งใช้สตริงที่ระบุประเภทเหตุการณ์และการมีส่วนร่วมที่จะรายงานเมื่อมีการทริกเกอร์เหตุการณ์นั้น คุณสามารถเรียกเมธอดด้วยประเภทเหตุการณ์ที่กําหนดเอง จากนั้นเรียก window.fence.reportEvent(eventType) จากเฟรมโฆษณาเพื่อทริกเกอร์ให้ส่งรายงาน

สมมติว่าคุณต้องการวัดจำนวนคลิกที่โฆษณาสำหรับแคมเปญหนึ่งได้รับ

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

ในฟังก์ชันการสร้างราคาเสนอ คุณจะกําหนดที่เก็บข้อมูลเป็นชุดค่าผสมของรหัสแคมเปญกับเหตุการณ์การคลิก แล้วเพิ่มค่าของที่เก็บข้อมูลนั้นเป็น 1 ทุกครั้งที่มีการเรียกเหตุการณ์

// Ad frame
window.fence.reportEvent('click');

จากนั้นคุณจะทริกเกอร์การส่งรายงานจากเฟรมโฆษณาในภายหลังได้โดยเรียกใช้ reportEvent(eventType)

ดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกใช้การสนับสนุนการรวมข้อมูลแบบส่วนตัวจากเฟรมจากคำอธิบาย

การรายงานผลการประมูลและประสิทธิภาพ

คุณสามารถรวบรวมผลการประมูลเมื่อทริกเกอร์โดยเหตุการณ์การชนะหรือแพ้การประมูลที่มี contributeToHistogramOnEvent(eventType, contribution) เมื่อคุณส่งคีย์เวิร์ดประเภทเหตุการณ์ที่จองไว้ (reserved.win, reserved.loss และ reserved.always)

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

เมื่อมีการระบุค่าฐานบางอย่าง เช่น ราคาเสนอที่ชนะ คุณจะกำหนดได้ว่าจะบวกหรือหักลบเท่าใดจากค่านั้น จากนั้นจึงรายงานค่าสุดท้าย ตัวอย่างเช่น หากคุณระบุราคาเสนอที่ชนะ 150 บาทเป็นค่าพื้นฐาน คุณอาจลบราคาเสนอ 60 บาทออกเพื่อคำนวณมูลค่าจริงที่ 90 บาทของจำนวนเงินที่แพ้การประมูล

การรายงานผลการประมูล

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

หากต้องการเรียนรู้ว่าคุณสูญเสียการประมูลไปเท่าใด ให้ลบราคาเสนอของคุณออกจากราคาเสนอที่ชนะโดยทำดังนี้

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

เมื่อส่งรายงานแล้ว ค่าที่รายงานจริงจะเป็น baseValue ที่ปรับขนาดแล้วโดยเลื่อนไปที่ค่า offset ดูข้อมูลเพิ่มเติมได้ในคำอธิบาย

การรายงานประสิทธิภาพ

ผู้ซื้อและผู้ขายสามารถรายงานระยะเวลาที่สคริปต์ใช้ในการทำงาน และเวลาที่ใช้ในการดึงข้อมูลสัญญาณที่เชื่อถือได้ ผู้ขายสามารถรวบรวมเวลาการสร้างราคาเสนอและเวลาสัญญาณการเสนอราคาที่เชื่อถือได้ของผู้ซื้อแต่ละรายเมื่อได้รับอนุญาตจากผู้ซื้อ

ดูคำอธิบายเพื่อดูข้อมูลเพิ่มเติม

การจัดเก็บสัญญาณการประมูลในพื้นที่เก็บข้อมูลที่ใช้ร่วมกัน

พื้นที่เก็บข้อมูลที่ใช้ร่วมกันคือพื้นที่เก็บข้อมูลที่ไม่ได้แบ่งพาร์ติชันและข้ามต้นทางที่คุณเขียนได้อย่างอิสระ แต่จะได้รับการปกป้องด้วยประตูเมื่ออ่านและประมวลผลค่าที่จัดเก็บไว้ โดยหนึ่งในประตูที่ใช้ได้สำหรับ Shared Storage API คือการรวมข้อมูลส่วนตัว คุณจะอ่านค่าในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้จากภายใน Worklet เท่านั้น และรายงานค่าเหล่านั้นได้โดยใช้การรวมข้อมูลส่วนตัวจาก Worklet

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

คุณสามารถเขียนคีย์และค่าลงในพื้นที่เก็บข้อมูลที่ใช้ร่วมกันได้จาก Worklet Protected Audience API

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

คุณสามารถโหลด Worklet พื้นที่เก็บข้อมูลที่ใช้ร่วมกันเพื่ออ่านและส่งค่าดังกล่าวด้วยการรวมแบบส่วนตัวได้ โดยทำดังนี้

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

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

ขั้นตอนถัดไปคือ

เราต้องการพูดคุยกับคุณเพื่อให้แน่ใจว่าเราได้สร้าง API ที่เหมาะสำหรับทุกคน

พูดคุยเกี่ยวกับ API

API นี้จะได้รับการจัดทำเอกสารและอภิปรายต่อสาธารณะเช่นเดียวกับ Privacy Sandbox API อื่นๆ

ทดลองใช้ API

คุณจะทดสอบและเข้าร่วมในการพูดคุยเกี่ยวกับ Protected Audience API ได้