Mã báo cáo

Tìm hiểu cách hoạt động của mã báo cáo trong phiên đấu giá sử dụng Protected Audience API

Tổng quan

Mã báo cáo là các giá trị nhận dạng liên kết với một quảng cáo mà bạn có thể sử dụng để tạo giá thầu, tính điểm giá thầu và báo cáo. Mã báo cáo do người mua cung cấp trong cấu hình nhóm mối quan tâm. Các mã này có trong generateBid(), scoreAd(), reportResult() và reportWin() theo nhiều điều kiện như được thảo luận trong hướng dẫn này.

Mã nhận dạng báo cáo cho phép bạn báo cáo giá trị nhận dạng cho một quảng cáo, đồng thời cho phép các trường hợp sử dụng như ưu đãi.

Mã báo cáo sẽ được cung cấp cho các hàm người mua và người bán trong Protected Audience
Phạm vi cung cấp mã báo cáo

Có 3 mã báo cáo thuộc 2 loại:

  • Mã báo cáo không thể chọn
    • buyerReportingId (một chuỗi)
    • buyerAndSellerReportingId (một chuỗi)
  • Mã báo cáo có thể chọn được
    • selectableBuyerAndSellerReportingIds (một mảng chuỗi)

Các mã báo cáo hoạt động theo cách khác nhau, tuỳ thuộc vào việc bạn có sử dụng mã báo cáo có thể chọn hay không. Khi bạn chỉ sử dụng mã báo cáo không thể chọn, các mã đó sẽ chỉ có sẵn trong các chức năng báo cáo. Khi sử dụng mã báo cáo có thể chọn cùng với mã báo cáo không thể chọn (nếu cần), tất cả mã được xác định cũng sẽ có sẵn bên trong generateBid() và scoreAd().

Mã báo cáo không thể chọn

Mã báo cáo được cung cấp cho chức năng của người mua và người bán trong Protected Audience
Khả năng sử dụng mã báo cáo có thể chọn

buyerReportingId và buyerAndSellerReportingId là các mã báo cáo không thể chọn được, được xác định trong cấu hình nhóm mối quan tâm. Mã này có trong các chức năng báo cáo của người mua và người bán. Hàm báo cáo của bên mua và bên bán sẽ chỉ chạy cho quảng cáo chiến thắng và các hàm này sẽ nhận được mã báo cáo được xác định cho quảng cáo chiến thắng đó.

Khi được dùng mà không có mã báo cáo có thể chọn, hàm báo cáo người mua sẽ nhận được buyerReportingId hoặc buyerAndSellerReportingId tuỳ thuộc vào hành vi ghi đè và hàm báo cáo của người bán sẽ nhận được buyerAndSellerReportingId. Nếu cả buyerReportingId và buyerAndSellerReportingId đều không được xác định trong cấu hình nhóm mối quan tâm, thì hàm reportWin() sẽ nhận được tên nhóm mối quan tâm (interestGroupName) của giá thầu giành chiến thắng.

Mã báo cáo không thể chọn sẽ không có trong generateBid() và scoreAd() nếu các mã này không được dùng cùng với mã báo cáo có thể chọn.

Mã báo cáo trong nhóm mối quan tâm

Mã báo cáo do người mua xác định cho mỗi quảng cáo trong một nhóm mối quan tâm:

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',
  }]
});

Báo cáo dành cho người bán

Trong giai đoạn báo cáo của người bán, giá trị buyerAndSellerReportingId được cung cấp cho reportResult():

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

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

Trước khi mã này được cung cấp trong reportResult(), mã này sẽ được kiểm tra để đảm bảo mã nhận dạng k-anonymity với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo không được kiểm tra cho đến ít nhất là Quý 1 năm 2025). Nếu không phải là k-anonymous, hàm reportResult() sẽ vẫn chạy nhưng giá trị mã báo cáo sẽ không có sẵn trong hàm này.

Báo cáo của người mua

Trong giai đoạn báo cáo của người mua của phiên đấu giá, reportWin() sẽ có một mã báo cáo. Nếu có nhiều mã báo cáo được xác định trong nhóm mối quan tâm, thì quy tắc ghi đè sẽ được áp dụng khi buyerAndSellerReportingId ghi đè buyerReportingId:

  • Nếu cả buyerAndSellerReportingId và buyerReportingId đều được xác định, thì buyerAndSellerReportingId sẽ ghi đè buyerReportingId và buyerAndSellerReportingId sẽ có sẵn bên trong reportWin().
  • Nếu chỉ định nghĩa buyerReportingId thì bạn có thể sử dụng buyerReportingId.
  • Nếu cả buyerAndSellerReportingId và buyerReportingId đều không được xác định, thì interestGroupName sẽ có sẵn.
function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

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

Mã báo cáo có sẵn trong reportWin() sẽ được kiểm tra để đảm bảo tính ẩn danh k-anonymity với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo bị loại trừ khỏi quá trình kiểm tra này ít nhất là cho đến Quý 1 năm 2025). Nếu không vượt qua được quy trình kiểm tra k-anonymity thì reportWin() sẽ vẫn chạy nhưng giá trị mã báo cáo sẽ không có trong hàm này.

Chỉ xác định buyerReportingId

Nếu chỉ có buyerReportingId được xác định trong cấu hình nhóm mối quan tâm:

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

Khi đó, buyerReportingId sẽ có trong reportWin():

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

Trước khi được cung cấp cho reportWin(), buyerReportingId sẽ được kiểm tra để đảm bảo tính k-ẩn danh với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo sẽ không được đưa vào quy trình kiểm tra này cho đến ít nhất là quý 1 năm 2025).

Chỉ xác định buyerAndSellerReportingId

Nếu chỉ có buyerAndSellerReportingId được xác định trong cấu hình nhóm mối quan tâm:

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

Khi đó, buyerAndSellerReportingId sẽ có trong reportWin():

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

Trước khi có thể sử dụng cho reportWin(), buyerAndSellerReportingId được kiểm tra để đảm bảo tính ẩn danh k-anonymity với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo bị loại trừ khỏi bước kiểm tra này ít nhất là cho đến Quý 1 năm 2025).

Cả buyerAndSellerReportingId và buyerReportingId đều được định nghĩa

Nếu cả buyerAndSellerReportingId và buyerReportingId đều được xác định trong cấu hình nhóm mối quan tâm:

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

Sau đó, chỉ buyerAndSellerReportingId có sẵn bên trong reportWin() do hành vi ghi đè:

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

Trước khi có thể sử dụng cho reportWin(), buyerAndSellerReportingId được kiểm tra để đảm bảo tính ẩn danh k-anonymity với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo bị loại trừ khỏi bước kiểm tra này ít nhất là cho đến Quý 1 năm 2025).

Cả buyerAndSellerReportingId và buyerReportingId đều không được xác định

Nếu bạn không xác định mã báo cáo trong cấu hình nhóm mối quan tâm:

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

Khi đó, nhóm đối tượng có cùng mối quan tâm name sẽ có sẵn trong reportWin():

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

Trước khi được cung cấp cho reportWin(), tên nhóm mối quan tâm (interestGroupName) được kiểm tra để đảm bảo tính an toàn k-anonymity với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo bị loại trừ khỏi bước kiểm tra này ít nhất là cho đến Quý 1 năm 2025).

Mã báo cáo có thể chọn

Mã báo cáo được cung cấp cho chức năng của người mua và người bán trong Protected Audience
Phạm vi cung cấp mã báo cáo có thể chọn

Mã báo cáo có thể chọn cho phép người mua chọn một mã trong quá trình tạo giá thầu và trình duyệt sẽ cung cấp giá trị đã chọn cho scoreAd() và các hàm báo cáo. Giá trị selectableBuyerAndSellerReportingIds (là một mảng chuỗi) được cung cấp cho generateBid() và người mua có thể trả về một mã nhận dạng đã chọn dưới dạng selectedBuyerAndSellerReportingId.

Các hàm generateBid() và scoreAd() sẽ chạy cho mỗi quảng cáo được xác định trong cấu hình nhóm mối quan tâm và nhận mã báo cáo cho mỗi quảng cáo. Chức năng báo cáo người mua và người bán sẽ chỉ chạy cho quảng cáo giành chiến thắng và các chức năng sẽ nhận ID báo cáo được xác định cho quảng cáo giành chiến thắng đó.

Khi mã báo cáo không thể chọn được dùng cùng với mã báo cáo có thể chọn, hành vi của các mã này sẽ thay đổi so với quy trình làm việc được mô tả trong phần trước. Không giống như hành vi ban đầu của mã báo cáo không thể chọn chỉ có sẵn bên trong các hàm báo cáo, mã báo cáo có thể chọn cho phép mã báo cáo không thể chọn xuất hiện trong generateBid() và scoreAd().

Nhóm đối tượng có cùng mối quan tâm

Trường mã báo cáo có thể chọn – selectableBuyerAndSellerReportingIds – là một mảng chuỗi do người mua xác định trong nhóm mối quan tâm của một quảng cáo. Bạn cũng có thể xác định mã báo cáo không thể chọn cùng với mã báo cáo có thể chọn:

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']
  }]
});

Tạo giá thầu của người mua

Nếu bạn xác định selectableBuyerAndSellerReportingIds trong cấu hình nhóm mối quan tâm, thì thuộc tính này sẽ có trong generateBid() cùng với các mã báo cáo khác đã được xác định.

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
  };
}

Người mua có thể chọn một trong các mã nhận dạng từ mảng selectableBuyerAndSellerReportingIds trong generateBid() và trả về mã nhận dạng đã chọn dưới dạng selectedBuyerAndSellerReportingId. Giá thầu sẽ bị từ chối nếu giá trị đã chọn không nằm trong mảng selectableBuyerAndSellerReportingIds. Nếu selectableBuyerAndSellerReportingIds được xác định trong cấu hình nhóm mối quan tâm và người mua không trả về selectedBuyerAndSellerReportingId từ generateBid(), thì mã báo cáo sẽ quay về hành vi được mô tả cho mã báo cáo không thể chọn.

Giá thầu có giá trị được trả về cho selectedbuyerAndSellerReportingId chỉ có thể giành chiến thắng trong phiên đấu giá nếu giá trị của selectedbuyerAndSellerReportingId là k-anonymous cùng với buyerAndSellerReportingId (nếu có), buyerReportingId (nếu có), chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo sẽ không được đưa vào quy trình kiểm tra này cho đến ít nhất là quý 1 năm 2025).

Tính điểm quảng cáo của người bán

Đối với người bán, selectedBuyerAndSellerReportingId do người mua trả về từ generateBid() sẽ có trong scoreAd(), cùng với buyerAndSellerReportingId nếu được xác định trong cấu hình nhóm mối quan tâm.

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

  // ...
}

Báo cáo của người bán

Đối với báo cáo của người bán, selectedBuyerAndSellerReportingId do người mua trả về từ generateBid() sẽ có sẵn trong reportResult(), cùng với buyerAndSellerReportingId, nếu được xác định trong nhóm mối quan tâm.

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

Nếu selectableBuyerAndSellerReportingIds được xác định trong cấu hình nhóm mối quan tâm và selectedBuyerAndSellerReportingId được trả về từ generateBid(), thì nó sẽ không thể thắng phiên đấu giá trừ phi selectedBuyerAndSellerReportingId và buyerAndSellerReportingId (nếu có) ẩn danh với chủ sở hữu nhóm mối quan tâm, URL tập lệnh đặt giá thầu, URL hiển thị và kích thước quảng cáo (kích thước quảng cáo bị loại trừ khỏi quá trình kiểm tra này cho đến ít nhất là Quý 1 năm 2025) và reportResult() sẽ không được thực thi cho giá thầu đó. Do đó, nếu reportResult() được gọi với giá trị cho selectedBuyerAndSellerReportingId, điều đó có nghĩa là các mã báo cáo đã vượt qua quy trình kiểm tra tính ẩn danh k-anonymity và tất cả mã báo cáo được xác định sẽ có trong reportResult().

Báo cáo của người mua

Nếu selectableBuyerAndSellerReportingIds được xác định trong cấu hình nhóm mối quan tâm và selectedBuyerAndSellerReportingId được trả về từ generateBid(), thì mọi mã báo cáo được xác định trong cấu hình nhóm mối quan tâm sẽ có sẵn. Xin lưu ý rằng tương tự như báo cáo của người bán, nếu mã báo cáo không ẩn danh k, thì chúng không thể thắng phiên đấu giá và reportWin() sẽ không chạy cho giá thầu đó.

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

  // ...
}

Ghi đè quy tắc

Ở đây, chúng tôi tóm tắt các quy tắc ghi đè cho cả mã báo cáo không thể chọn và mã báo cáo có thể chọn. Trình duyệt nào sau đây xác định selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId và tên nhóm mối quan tâm được chuyển đến reportWin():

  • Nếu selectedBuyerAndSellerReportingId được trả về từ một giá thầu, thì selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (nếu được xác định trong nhóm mối quan tâm) và buyerReportingId (nếu được xác định trong nhóm mối quan tâm) đều có sẵn để báo cáo.
  • Ngược lại, nếu buyerAndSellerReportingId được xác định trong nhóm mối quan tâm thì chỉ có buyerAndSellerReportingId để báo cáo.
  • Nếu không, nếu buyerReportingId được xác định trong nhóm mối quan tâm, thì chỉ có buyerReportingId mới có thể dùng để báo cáo.
  • Nếu không, bạn chỉ có thể báo cáo nhóm quan tâm name.

Bảng sau đây mô tả hành vi ghi đè:

Các mã báo cáo có được xác định trong cấu hình nhóm mối quan tâm không? Có mã báo cáo
selectableBuyerAnd
SellerReportingIds 		buyerAndSeller
ReportingId 		buyerReportingId reportWin() reportResult()
Có và đã chọn
trong generateBid() 		Không bắt buộc Không bắt buộc 1) selectableBuyerAnd
SellerReportingIds

2) buyerAndSeller
ReportingId (nếu xác định)

3) buyerReportingId (nếu được xác định) 		1) selectableBuyerAnd
SellerReportingIds

2) buyerAndSeller
ReportingId (nếu được xác định)
Không, hoặc chưa được chọn
trong generateBid()		 Có Bị bỏ qua buyerAndSeller
ReportingId		 buyerAndSeller
ReportingId
Không hoặc chưa chọn
trong generateBid()		 Không Có buyerReportingId Không có
Không hoặc chưa được chọn
trong generateBid()		 Không Không interestGroupName Không có

Tham gia và chia sẻ ý kiến phản hồi