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

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

ภาพรวม

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

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

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

รหัสการรายงานมี 3 ประเภท ได้แก่

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

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

ในระหว่างขั้นตอนการรายงานผู้ซื้อของการประมูล จะมีรหัสการรายงานหนึ่งรหัสพร้อมใช้งานสำหรับ reportWin() หากมีการกำหนดรหัสการรายงานมากกว่า 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

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

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(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  } = browserSignals;

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

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

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

หากมีการกำหนด selectableBuyerAndSellerReportingIds ในการกำหนดค่ากลุ่มความสนใจ และมีการส่งคืน selectedBuyerAndSellerReportingId จาก generateBid() รหัสการรายงานทั้งหมดที่กำหนดไว้ในการกำหนดค่ากลุ่มความสนใจจะพร้อมใช้งาน โปรดทราบว่าคล้ายกับการรายงานของผู้ขาย หากรหัสการรายงานไม่ใช่รหัสที่ระบุตัวบุคคล ก็จะไม่ชนะการประมูลและ 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) selectableBuyerAnd
SellerReportingIds


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

3) buyerReportingId (หากกําหนดไว้)
1) selectableBuyerAnd
SellerReportingIds


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

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

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