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

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

ภาพรวม

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

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

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

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

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

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

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

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

รหัสการรายงานที่เลือกได้ช่วยให้ผู้ซื้อเลือกรหัสระหว่างการสร้างราคาเสนอได้ และเบราว์เซอร์จะทําให้ค่าที่เลือกพร้อมใช้งานสําหรับ 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 ในการกำหนดค่ากลุ่มความสนใจ 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
  };
}

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

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

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

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

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

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

• ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสการรายงานได้ที่ส่วนรหัสการรายงานของคําอธิบายกลุ่มเป้าหมายที่ได้รับการคุ้มครอง
• GitHub: ถามคําถามและติดตามการพูดคุยในปัญหาที่เก็บ API
• W3C: พูดคุยเกี่ยวกับกรณีการใช้งานในอุตสาหกรรมในการโทรของ WICG
• ประกาศ: เข้าร่วมหรือดูรายชื่ออีเมล
• การสนับสนุนนักพัฒนาซอฟต์แวร์ Privacy Sandbox: ถามคําถามและเข้าร่วมการสนทนาในที่เก็บข้อมูลการสนับสนุนนักพัฒนาซอฟต์แวร์ Privacy Sandbox
• Chromium: รายงานข้อบกพร่องของ Chromium เพื่อสอบถามคำถามเกี่ยวกับการนำใช้งานที่พร้อมให้ทดสอบใน Chrome