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á Protected Audience

Tổng quan

Mã báo cáo là giá trị nhận dạng được liên kết với một quảng cáo có thể 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 và chúng sẽ xuất hiện trong generateBid(), scoreAd(), reportResult() và reportWin() theo nhiều điều kiện được thảo luận trong hướng dẫn này.

Mã 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.

Tình trạng sử dụng 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 được
  • buyerReportingId (một chuỗi)
  • buyerAndSellerReportingId (một chuỗi)
• Mã báo cáo có thể chọn được
  • selectableBuyerAndSellerReportingIds (mảng chuỗi)

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 chỉ sử dụng mã báo cáo không thể chọn, các mã đó chỉ có sẵn bên trong các hàm 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().

Lưu ý quan trọng: Mã nhận dạng báo cáo được kiểm tra để đảm bảo tính ẩn danh k trước khi có sẵn trong các hàm báo cáo (reportResult() và reportWin()).

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

Khả năng sử dụng mã báo cáo có thể chọn

buyerReportingId và buyerAndSellerReportingId là mã báo cáo không thể chọn được được xác định trong cấu hình nhóm đối tượng có cùng mối quan tâm và có sẵn trong các hàm báo cáo người mua và người bán. Các hàm báo cáo của người mua và người 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 sử dụng mà không có mã báo cáo có thể chọn, hàm báo cáo của 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 không xác định buyerReportingId hoặc buyerAndSellerReportingId 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 chiến thắng.

Bạn không thể sử dụng mã nhận dạng không thể chọn được bên trong generateBid() và scoreAd() nếu không sử dụng cùng với mã nhận dạng báo cáo có thể chọn được.

Mã nhận dạng trong báo cáo của nhóm mối quan tâm

Mã báo cáo do người mua xác định cho từng 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 cho người bán, giá trị buyerAndSellerReportingId sẽ có sẵn cho reportResult():

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

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

Trước khi có sẵn trong reportResult(), mã nhận dạng sẽ được kiểm tra để đảm bảo tính 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 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). Nếu không phải là k-anonymous, hàm reportResult() vẫn sẽ chạy nhưng giá trị mã báo cáo sẽ không có trong hàm.

Báo cáo người mua

Trong giai đoạn báo cáo của người mua trong phiên đấu giá, reportWin() sẽ có một mã báo cáo. Nếu bạn xác định nhiều mã báo cáo trong nhóm mối quan tâm, thì hệ thống sẽ áp dụng quy tắc ghi đè, trong đó 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 trong reportWin().
• Nếu chỉ xác định buyerReportingId thì buyerReportingId sẽ có sẵn.
• Nếu không xác định buyerAndSellerReportingId hoặc buyerReportingId, 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 bên trong reportWin() được kiểm tra để đảm bảo tính 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 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). Nếu không vượt qua được quy trình kiểm tra tính k-ẩn danh, thì reportWin() vẫn sẽ chạy nhưng giá trị mã báo cáo sẽ không có trong hàm.

Chỉ xác định buyerReportingId

Nếu chỉ 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',
  }]
});

Sau đó, buyerReportingId sẽ có sẵn bên 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ỉ 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',
  }]
});

Sau đó, buyerAndSellerReportingId sẽ có sẵn bên trong reportWin():

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

Trước khi được cung cấp cho reportWin(), buyerAndSellerReportingId 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).

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

Nếu cả buyerAndSellerReportingId và 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',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

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

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

Trước khi được cung cấp cho reportWin(), buyerAndSellerReportingId 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).

Không xác định buyerAndSellerReportingId hoặc buyerReportingId

Nếu không có mã nhận dạng báo cáo nào đượ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`,
  }]
});

Sau đó, nhóm mối quan tâm name sẽ có sẵn bê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) 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).

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

Khả năng sử dụng mã báo cáo có thể chọn được

Mã nhận dạng báo cáo có thể chọn cho phép người mua chọn một mã nhận dạng 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ã đã chọn dưới dạng selectedBuyerAndSellerReportingId.

Hàm generateBid() và scoreAd() sẽ chạy cho từng 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 từng quảng cáo. Các hàm báo cáo của người mua và người 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 mã báo cáo không thể chọn được được sử dụng cùng với mã báo cáo có thể chọn được, hành vi của các mã này sẽ thay đổi so với quy trình công 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ó trong các hàm báo cáo, mã báo cáo có thể chọn cũng cho phép mã báo cáo không thể chọn có trong generateBid() và scoreAd().

Lưu ý: Các mã báo cáo có thể chọn sẽ có trong phiên bản ổn định trong M130. Trước khi các mã báo cáo có thể chọn đạt đến trạng thái ổn định, bạn có thể kiểm thử các mã này bằng cách chạy Canary M130 từ dòng lệnh với cờ --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

Nhóm mối quan tâm

Trường mã báo cáo có thể chọn – selectableBuyerAndSellerReportingIds – là một mảng các chuỗi do người mua xác định trong nhóm mối quan tâm cho 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 selectableBuyerAndSellerReportingIds được xác định trong cấu hình nhóm mối quan tâm, thì mã này sẽ có sẵn bên trong generateBid() cùng với các mã báo cáo khác đã được xác định.

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

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 có 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 lại 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ể thắng 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ẽ bị loại trừ khỏi quy trình kiểm tra này cho đến ít nhất là quý 1 năm 2025).

Lưu ý: Trong trường hợp generateBid() chạy lại vì lệnh gọi ban đầu không tạo ra giá thầu nào có quảng cáo vượt qua quy trình kiểm tra tính k-ẩn danh, thì selectableBuyerAndSellerReportingIds không vượt qua quy trình kiểm tra tính k-ẩn danh sẽ không xuất hiện trong nhóm mối quan tâm khi chạy lại.

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 dành cho người bán

Đối với báo cáo dành cho người bán, selectedBuyerAndSellerReportingId do người mua trả về từ generateBid() sẽ có 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ì giá thầu đó không thể thắng phiên đấu giá trừ phi selectedBuyerAndSellerReportingId và buyerAndSellerReportingId (nếu có) là k-anonymous 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ẽ bị loại trừ khỏi quy 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 một giá trị cho selectedBuyerAndSellerReportingId, thì điều đó có nghĩa là mã báo cáo đã vượt qua quy trình kiểm tra tính k-ẩn danh và tất cả mã báo cáo được xác định sẽ có trong reportResult().

Báo cáo 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ì tất cả 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 phải là k-anonymous, 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

Sau đây là thông tin tóm tắt về 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 sẽ xác định selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId và tên nhóm mối quan tâm nào được truyền đến reportWin() bằng logic sau:

• 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.
• Nếu không, 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 để báo cáo.
• Nếu không, bạn chỉ có thể báo cáo nhóm mối quan tâm name.

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

Mã nhận dạng báo cáo có được xác định trong cấu hình nhóm mối quan tâm không?			Mã báo cáo có sẵn
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) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (nếu được xác định) 3) buyerReportingId (nếu được xác định)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (nếu được xác định)
Không hoặc chưa 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 chọn trong generateBid()	Không	Không	interestGroupName	Không có

Tương tác và chia sẻ ý kiến phản hồi

• Để tìm hiểu thêm về mã nhận dạng trong báo cáo, hãy xem phần Mã nhận dạng trong báo cáo của bài viết giải thích về Protected Audience.
• GitHub: Đặt câu hỏi và theo dõi các cuộc thảo luận trong các vấn đề trên kho lưu trữ API.
• W3C: Thảo luận về các trường hợp sử dụng trong ngành trong cuộc gọi của WICG.
• Thông báo: Tham gia hoặc xem danh sách gửi thư.
• Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư: Hỏi và tham gia thảo luận trên kho lưu trữ Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư.
• Chromium: Gửi lỗi Chromium để đặt câu hỏi về cách triển khai có thể kiểm thử trong Chrome.