รหัสการรายงาน

ดูวิธีการทำงานของรหัสการรายงานในการประมูลที่ใช้ Protected Audience

ภาพรวม

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

รหัสการรายงานช่วยให้คุณรายงานตัวระบุสําหรับโฆษณา และยังเปิดใช้กรณีการใช้งานต่างๆ เช่น ดีล ได้อีกด้วย

รหัสการรายงานจะพร้อมใช้งานสำหรับฟังก์ชันผู้ซื้อและผู้ขายของ Protected Audience API
ความพร้อมใช้งานของรหัสการรายงาน

รหัสการรายงานมี 3 ประเภท 2 ชนิด ดังนี้

  • รหัสการรายงานที่เลือกไม่ได้
    • buyerReportingId (สตริง)
    • buyerAndSellerReportingId (สตริง)
  • รหัสการรายงานที่เลือกได้
    • selectableBuyerAndSellerReportingIds (อาร์เรย์ของสตริง)

รหัสการรายงานจะทํางานแตกต่างกันไป ขึ้นอยู่กับว่ามีการใช้รหัสการรายงานที่เลือกได้หรือไม่ เมื่อใช้เฉพาะรหัสการรายงานที่เลือกไม่ได้ รหัสเหล่านั้นจะพร้อมใช้งานภายในฟังก์ชันการรายงานเท่านั้น เมื่อใช้รหัสการรายงานที่เลือกได้พร้อมกับรหัสการรายงานที่เลือกไม่ได้ (หากจำเป็น) รหัสทั้งหมดที่กำหนดไว้จะพร้อมใช้งานใน generateBid() และ scoreAd() ด้วย

รหัสการรายงานที่เลือกไม่ได้

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

buyerReportingId และ buyerAndSellerReportingId คือรหัสการรายงานที่เลือกไม่ได้ซึ่งกำหนดไว้ในการกำหนดค่ากลุ่มความสนใจซึ่งจะพร้อมใช้งานในฟังก์ชันการรายงานของผู้ซื้อและผู้ขาย ฟังก์ชันการรายงานของผู้ซื้อและผู้ขายจะทํางานสําหรับโฆษณาที่ชนะเท่านั้น และฟังก์ชันจะได้รับรหัสการรายงานที่กําหนดไว้สําหรับโฆษณาที่ชนะนั้น

เมื่อใช้โดยไม่มีรหัสการรายงานที่เลือกได้ ฟังก์ชันการรายงานของผู้ซื้อจะได้รับ buyerReportingId หรือ buyerAndSellerReportingId ขึ้นอยู่กับลักษณะการทำงานของการเขียนทับ และฟังก์ชันการรายงานของผู้ขายจะได้รับ buyerAndSellerReportingId หากไม่ได้กำหนดทั้ง buyerReportingId และ buyerAndSellerReportingId ในการกำหนดค่ากลุ่มความสนใจ ฟังก์ชัน reportWin() จะได้รับชื่อกลุ่มความสนใจ (interestGroupName) ของราคาเสนอที่ชนะ

รหัสที่เลือกไม่ได้จะใช้ไม่ได้ภายใน generateBid() และ scoreAd() หากไม่ได้ใช้ร่วมกับรหัสการรายงานที่เลือกได้

การรายงานรหัสในกลุ่มความสนใจ

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

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

การรายงานของผู้ขาย

ในระหว่างระยะการรายงานของผู้ขาย ค่า buyerAndSellerReportingId จะพร้อมใช้งานสำหรับ reportResult() ดังนี้

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

ก่อนที่รหัสจะพร้อมใช้งานภายใน reportResult() ระบบจะตรวจสอบ k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) หากไม่ใช่ k-anonymous reportResult() ฟังก์ชันจะยังคงทํางาน แต่ค่ารหัสการรายงานจะไม่พร้อมใช้งานภายในฟังก์ชัน

การรายงานของผู้ซื้อ

ในระหว่างระยะการรายงานของผู้ซื้อของการประมูล reportWin() จะได้รับรหัสการรายงาน 1 รายการ หากมีการกําหนดรหัสการรายงานมากกว่า 1 รายการในกลุ่มความสนใจ ระบบจะใช้กฎการเขียนทับที่ buyerAndSellerReportingId เขียนทับ buyerReportingId ดังนี้

  • หากกำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId buyerAndSellerReportingId จะเขียนทับ buyerReportingId และ buyerAndSellerReportingId จะพร้อมใช้งานภายใน reportWin()
  • หากกำหนดเฉพาะ buyerReportingId ไว้ buyerReportingId จะพร้อมใช้งาน
  • หากไม่ได้กำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId interestGroupName จะพร้อมใช้งาน
function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

ระบบจะตรวจสอบรหัสการรายงานที่พร้อมใช้งานภายใน reportWin() เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนกว่าจะถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) หากไม่ผ่านการตรวจสอบ k-anonymity reportWin() จะยังคงทํางานต่อไป แต่ค่ารหัสการรายงานจะใช้ไม่ได้ภายในฟังก์ชัน

กำหนด buyerReportingId เท่านั้น

หากกำหนดเฉพาะ buyerReportingId ในการกำหนดค่ากลุ่มตามความสนใจ

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

จากนั้น buyerReportingId จะพร้อมใช้งานภายใน reportWin()

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)

กำหนดเฉพาะ buyerAndSellerReportingId

หากกำหนดเฉพาะ buyerAndSellerReportingId ในการกำหนดค่ากลุ่มตามความสนใจ

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

จากนั้น buyerAndSellerReportingId จะพร้อมใช้งานภายใน reportWin()

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerAndSellerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)

กำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId

หากกำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId ในการกำหนดค่ากลุ่มความสนใจ

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

จากนั้นจะมีเพียง buyerAndSellerReportingId ใน reportWin() เนื่องจากลักษณะการทำงานของการเขียนทับ

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบ buyerAndSellerReportingId เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ขนาดโฆษณาจะได้รับการยกเว้นจากการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)

ไม่ได้กำหนดทั้ง buyerAndSellerReportingId และ buyerReportingId

หากไม่ได้กำหนดรหัสการรายงานทั้ง 2 รายการในการกำหนดค่ากลุ่มความสนใจ ให้ทำดังนี้

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

จากนั้นกลุ่มความสนใจ name จะพร้อมใช้งานภายใน reportWin()

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

ก่อนที่จะพร้อมใช้งานสำหรับ reportWin() ระบบจะตรวจสอบชื่อกลุ่มความสนใจ (interestGroupName) เพื่อหา k-anonymity กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนกว่าจะถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)

รหัสการรายงานที่เลือกได้

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

รหัสการรายงานที่เลือกได้ช่วยให้ผู้ซื้อเลือกรหัสได้ในระหว่างการสร้างราคาเสนอ และเบราว์เซอร์จะทำให้ค่าที่เลือกพร้อมใช้งานสำหรับ scoreAd() และฟังก์ชันการรายงาน selectableBuyerAndSellerReportingIds ซึ่งเป็นอาร์เรย์ของสตริงจะระบุไว้ใน generateBid() และผู้ซื้อจะส่งคืนรหัสที่เลือก 1 รายการเป็น selectedBuyerAndSellerReportingId ได้

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

เมื่อใช้รหัสการรายงานที่เลือกไม่ได้ร่วมกับรหัสการรายงานที่เลือกได้ ลักษณะการทำงานของรหัสการรายงานที่เลือกไม่ได้จะเปลี่ยนไปจากเวิร์กโฟลว์ที่อธิบายไว้ในส่วนก่อนหน้า ซึ่งแตกต่างจากลักษณะการทำงานเริ่มต้นของรหัสการรายงานที่เลือกไม่ได้ซึ่งใช้ได้เฉพาะภายในฟังก์ชันการรายงาน รหัสการรายงานที่เลือกได้จะช่วยให้รหัสการรายงานที่เลือกไม่ได้พร้อมใช้งานภายใน generateBid() และ scoreAd() ด้วย

กลุ่มความสนใจ

ฟิลด์รหัสการรายงานที่เลือกได้ - selectableBuyerAndSellerReportingIds - คืออาร์เรย์ของสตริงที่ผู้ซื้อกำหนดในกลุ่มความสนใจสำหรับโฆษณา คุณยังกําหนดรหัสการรายงานที่เลือกไม่ได้ควบคู่ไปกับรหัสการรายงานที่เลือกได้ด้วย

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

การสร้างราคาเสนอของผู้ซื้อ

หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ ก็จะใช้ได้ภายใน generateBid() พร้อมกับรหัสการรายงานอื่นๆ ที่กำหนดไว้

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

ผู้ซื้อสามารถเลือก 1 ในรหัสจากอาร์เรย์ selectableBuyerAndSellerReportingIds ใน generateBid() และส่งคืนรหัสที่เลือกเป็น selectedBuyerAndSellerReportingId ระบบจะปฏิเสธราคาเสนอหากค่าที่เลือกไม่อยู่ในอาร์เรย์ selectableBuyerAndSellerReportingIds หากกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และผู้ซื้อไม่แสดง selectedBuyerAndSellerReportingId จาก generateBid() รหัสการรายงานจะเปลี่ยนกลับเป็นลักษณะการทำงานที่อธิบายไว้สำหรับรหัสการรายงานที่เลือกไม่ได้

ราคาเสนอที่มีค่าที่ส่งคืนสำหรับ selectedbuyerAndSellerReportingId อาจชนะการประมูลได้ก็ต่อเมื่อค่าของ selectedbuyerAndSellerReportingId เป็นแบบ k-anonymous ร่วมกับ buyerAndSellerReportingId (หากมี), buyerReportingId (หากมี), เจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย)

การให้คะแนนโฆษณาของผู้ขาย

สำหรับผู้ขาย selectedBuyerAndSellerReportingId ที่ผู้ซื้อส่งคืนจาก generateBid() จะพร้อมใช้งานใน scoreAd() พร้อมกับ buyerAndSellerReportingId หากมีการกำหนดไว้ในการกำหนดค่ากลุ่มความสนใจ

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

การรายงานของผู้ขาย

สำหรับการรายงานของผู้ขาย selectedBuyerAndSellerReportingId ที่ผู้ซื้อส่งคืนจาก generateBid() จะพร้อมใช้งานใน reportResult() พร้อมกับ buyerAndSellerReportingId หากมีการกำหนดไว้ในกลุ่มความสนใจ

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และ selectedBuyerAndSellerReportingId แสดงผลจาก generateBid() ก็จะชนะการประมูลไม่ได้ เว้นแต่ selectedBuyerAndSellerReportingId และ buyerAndSellerReportingId (หากมี) จะเป็นแบบ k-anonymous กับเจ้าของกลุ่มความสนใจ, URL สคริปต์การเสนอราคา, URL การแสดงผล และขนาดโฆษณา (ระบบจะไม่รวมขนาดโฆษณาในการตรวจสอบนี้จนถึงไตรมาสที่ 1 ปี 2025 เป็นอย่างน้อย) และจะไม่ดำเนินการ reportResult() สำหรับราคาเสนอนั้น ดังนั้น หากมีการเรียกใช้ reportResult() โดยมีค่าสำหรับ selectedBuyerAndSellerReportingId แสดงว่ารหัสการรายงานผ่านการตรวจสอบ k-anonymity และรหัสการรายงานทั้งหมดที่กำหนดจะพร้อมใช้งานภายใน reportResult()

การรายงานของผู้ซื้อ

หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และ selectedBuyerAndSellerReportingId ได้รับจาก generateBid() รหัสการรายงานทั้งหมดที่กำหนดในการกำหนดค่ากลุ่มความสนใจจะพร้อมใช้งาน โปรดทราบว่าเช่นเดียวกับการรายงานของผู้ขาย หากรหัสการรายงานไม่เป็นแบบ k-anonymous รหัสเหล่านั้นจะไม่ชนะการประมูลและreportWin()จะไม่ทํางานสําหรับราคาเสนอนั้น

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

กฎการเขียนทับ

เราจะสรุปกฎการลบล้างสำหรับทั้งรหัสการรายงานที่เลือกไม่ได้และรหัสการรายงานที่เลือกได้ เบราว์เซอร์จะเป็นตัวกำหนดว่า selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId และชื่อกลุ่มความสนใจใดจะส่งไปยัง reportWin() โดยใช้ตรรกะต่อไปนี้

  • หากระบบแสดงผล selectedBuyerAndSellerReportingId จากราคาเสนอ selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (หากกำหนดไว้ในกลุ่มความสนใจ) และ buyerReportingId (หากกำหนดไว้ในกลุ่มความสนใจ) จะพร้อมใช้งานสำหรับการรายงาน
  • มิฉะนั้น หากมีการกำหนด buyerAndSellerReportingId ในกลุ่มความสนใจ ก็จะมีเฉพาะ buyerAndSellerReportingId เท่านั้นที่ใช้ได้สำหรับการรายงาน
  • มิฉะนั้น หากมีการกำหนด buyerReportingId ในกลุ่มความสนใจ ก็จะมีเฉพาะ buyerReportingId เท่านั้นที่ใช้ได้สำหรับการรายงาน
  • มิฉะนั้น จะมีเพียงกลุ่มความสนใจ name เท่านั้นที่พร้อมสำหรับการรายงาน

ตารางต่อไปนี้อธิบายลักษณะการทำงานของการเขียนทับ

มีการกำหนดรหัสการรายงานในการกำหนดค่ากลุ่มความสนใจหรือไม่ รหัสการรายงานที่ใช้ได้
selectableBuyerAnd
SellerReportingIds
buyerAndSeller
ReportingId
buyerReportingId reportWin() reportResult()
ใช่ และเลือก
ใน generateBid()
ไม่บังคับ ไม่บังคับ 1) selectedBuyerAnd
SellerReportingIds


2) buyerAndSeller
ReportingId
(หากกำหนดไว้)

3) buyerReportingId (หากกำหนดไว้)
1) selectedBuyerAnd
SellerReportingIds


2) buyerAndSeller
ReportingId
(หากกำหนด)

ไม่ได้เลือก
ใน generateBid()
มี ละเว้นแล้ว buyerAndSeller
ReportingId
buyerAndSeller
ReportingId
ไม่ได้เลือก
ใน generateBid()
ไม่ มี buyerReportingId ไม่มี
ไม่ได้เลือก
ใน generateBid()
ไม่ ไม่ interestGroupName ไม่มี

มีส่วนร่วมและแชร์ความคิดเห็น