報表 ID

瞭解報表 ID 在 Protected Audience 競價中的運作方式

總覽

報表 ID 是與廣告相關聯的 ID，可用於產生出價、設定出價及製作報表。回報 ID 是由買方在興趣群組設定中提供，並在 generateBid()、scoreAd()、reportResult() 和 reportWin() 中，根據本指南所述的各種條件提供。

您可以使用報表 ID 回報廣告 ID，並啟用特惠等用途。

報表 ID 可用性

報表 ID 分為兩種類型：

• 無法選取的報表 ID
  • buyerReportingId (字串)
  • buyerAndSellerReportingId (字串)
• 可選取的報表 ID
  • selectableBuyerAndSellerReportingIds (字串陣列)

視使用可選取的報表 ID 而定，報表 ID 的行為會有所不同。如果只使用無法選取的報表 ID，這類 ID 只能在報表函式中使用。使用可選取的報表 ID ，以及視需要不可選取的報表 ID 時，定義的所有 ID 也會在 generateBid() 和 scoreAd() 中使用。

重要事項： 報表 ID 會先檢查 k-anonymity，再用於報表功能 (reportResult() 和 reportWin())。

無法選取的報表 ID

可選取的報表 ID 可用性

buyerReportingId 和 buyerAndSellerReportingId 是興趣群組設定中定義的不可選報表 ID，可用於買方和賣方報表函式。系統只會針對勝出的廣告執行買方和賣方報表功能，而且函式將收到為勝出廣告定義的報表 ID。

在沒有可選取的報表 ID 使用時，買方報表功能會收到 buyerReportingId 或 buyerAndSellerReportingId (視覆寫行為而定)，而賣方報表函式會收到 buyerAndSellerReportingId。如果興趣群組設定中未定義 buyerReportingId 或 buyerAndSellerReportingId，則 reportWin() 函式會收到得標出價的興趣群組名稱 (interestGroupName)。

如果無法選取的 ID 未搭配可選取的報表 ID 使用，就無法在 generateBid() 和 scoreAd() 中使用。

興趣群組中的報表 ID

報表 ID 是由買方針對興趣群組中的每則廣告定義：

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

賣方報表

在賣方報表階段，reportResult() 可以使用 buyerAndSellerReportingId 值：

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

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

在 reportResult() 內提供 ID 之前，系統會先檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前才會排除廣告大小)。如果這個值不是 k 匿名，reportResult() 函式仍會執行，但函式不會顯示報表 ID 值。

買方報表

在競價的買方報表階段，reportWin() 會有一個報表 ID。如果興趣群組中定義了多個報表 ID，系統會套用覆寫規則，其中 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() 中提供的報表 ID，檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前會排除廣告大小)。如果未通過 k-anonymity 檢查，reportWin() 仍可執行，但函式中不會顯示報表 ID 值。

只定義 buyerReportingId

如果興趣群組設定中只定義了 buyerReportingId：

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

然後在 reportWin() 中使用 buyerReportingId：

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

在提供給 reportWin() 之前，buyerReportingId 會先檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前，不會列入這項檢查的 k 匿名性)。

只有買方 AndSellerReportingId

如果興趣群組設定中只定義了 buyerAndSellerReportingId：

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

然後在 reportWin() 中使用 buyerAndSellerReportingId：

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

在提供給 reportWin() 之前，buyerAndSellerReportingId 會先檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前，不會列入這項檢查的 k 匿名性)。

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

由於覆寫行為，因此 reportWin() 中只有 buyerAndSellerReportingId 可供使用：

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

在提供給 reportWin() 之前，buyerAndSellerReportingId 會先檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前，不會列入這項檢查的 k 匿名性)。

未定義 buyerAndSellerReportingId 和 buyerReportingId

如果興趣群組設定中未定義任何報表 ID：

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

接著，您可在 reportWin() 中找到興趣群組 name：

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

提供 reportWin() 之前，系統會先檢查興趣群組名稱 (interestGroupName) 與興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前會排除廣告大小)。

可選報表 ID

報表 ID 可用性和可選取的報表 ID

買方選取的報表 ID 後，就能在出價產生期間選取 ID，而瀏覽器會將所選值提供給 scoreAd() 和報表功能。selectableBuyerAndSellerReportingIds 值 (字串陣列) 會提供給 generateBid()，買方可以傳回一個選定的 ID 做為 selectedBuyerAndSellerReportingId。

系統會針對興趣群組設定中定義的每則廣告執行 generateBid() 和 scoreAd() 函式，並收到每則廣告的報表 ID。系統只會針對勝出的廣告執行買方和賣方報表功能，而且函式將收到為勝出廣告定義的報表 ID。

無法選取的報表 ID 搭配可選取的報表 ID 使用時，其行為會在上一節所述的工作流程中改變。與最初的行為不同，可選報表 ID 只能在報表函式中使用，但可選報表 ID 則可在 generateBid() 和 scoreAd() 中使用。

注意：可選報表 ID 將於 M130 穩定版推出。在可選取的報表 ID 到達穩定版之前，您可以先從加上旗標 --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport 的指令列啟動 Canary M130 進行測試。

興趣群組

可選取的報表 ID 欄位「selectableBuyerAndSellerReportingIds」是由買方在廣告興趣群組中定義的字串陣列。無法選取的報表 ID 也可以和可選取的報表 ID 一起定義：

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，這個值就會連同其他已定義的報表 ID 提供給 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
  };
}

買方可以從 generateBid() 的 selectableBuyerAndSellerReportingIds 陣列中選擇其中一個 ID，並以 selectedBuyerAndSellerReportingId 傳回所選 ID。如果所選值不在 selectableBuyerAndSellerReportingIds 陣列中，系統會拒絕出價。如果興趣群組設定中已定義 selectableBuyerAndSellerReportingIds，而且買方並未從 generateBid() 傳回 selectedBuyerAndSellerReportingId，則報表 ID 會還原為無法選取的報表 ID 所述的行為。

傳回 selectedbuyerAndSellerReportingId 值的出價只有在 selectedbuyerAndSellerReportingId 值同時是 k 匿名和 buyerAndSellerReportingId (如果有的話)、buyerReportingId (如果有的話)、興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季之前才會從這項檢查中排除)，才能贏得競價。

注意： 如果 generateBid() 因為初始叫用並未產生任何通過 k-anonymity 檢查的廣告出價，導致 generateBid() 重新執行，那麼若是未通過 k-anonymity 檢查的廣告，則不會出現未通過 k-anonymity 檢查的 selectableBuyerAndSellerReportingId，

賣方廣告的評分

如果是賣方，買方從 generateBid() 傳回的 selectedBuyerAndSellerReportingId 將出現在 scoreAd() 中；如果已在興趣群組設定中定義，則 buyerAndSellerReportingId 也會出現在 scoreAd() 中。

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

  // ...
}

賣方報表

對於賣方報表，買方從 generateBid() 傳回的 selectedBuyerAndSellerReportingId 將出現在 reportResult() 中；如果已在興趣群組中定義，buyerAndSellerReportingId 也會出現在這些屬性中。

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

如果在興趣群組設定中定義了 selectableBuyerAndSellerReportingIds，而 selectedBuyerAndSellerReportingId 從 generateBid() 傳回，則該出價就無法贏得競價，除非興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少要到 2025 年第 1 季，才會在此檢查中排除廣告大小)，否則系統不會為該出價執行 reportResult()。selectedBuyerAndSellerReportingIdbuyerAndSellerReportingId因此，如果使用 selectedBuyerAndSellerReportingId 的值呼叫 reportResult()，就代表通過 k-anonymity 檢查的報表 ID，所有定義的報表 ID 都會出現在 reportResult() 中。

買方報表

如果興趣群組設定中已定義 selectableBuyerAndSellerReportingIds，而 selectedBuyerAndSellerReportingId 從 generateBid() 傳回，那麼興趣群組設定中定義的所有報表 ID 都會開放使用。請注意，與賣方報表類似，如果報表 ID 不是 k 匿名，就無法贏得競價，reportWin() 也不會針對該出價執行。

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

  // ...
}

覆寫規則

以下摘要列出無法選取的報表 ID 和可選取報表 ID 的覆寫規則。哪一個 selectableBuyerAndSellerReportingIds、buyerAndSellerReportingId、buyerReportingId 和興趣群組名稱會傳遞給 reportWin()，是由採用以下邏輯的瀏覽器決定：

• 如果出價傳回 selectedBuyerAndSellerReportingId，那麼報表就會提供 selectedBuyerAndSellerReportingId、buyerAndSellerReportingId (如已定義興趣群組) 和 buyerReportingId (如果已定義興趣群組)。
• 否則，如果興趣群組已定義 buyerAndSellerReportingId，報表就只會採用 buyerAndSellerReportingId。
• 否則，如果興趣群組已定義 buyerReportingId，報表就只會採用 buyerReportingId。
• 否則，只有「name」興趣群組可用於報表。

下表說明覆寫行為：

興趣群組設定中是否已定義報表 ID？			可用的報表 ID
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	無

互動並分享意見回饋

• 如要進一步瞭解報表 ID，請參閱 Protected Audience 說明的「報表 ID」一節。
• GitHub：在 API 存放區中提出問題並討論相關問題。
• W3C：透過 WICG 通話會議討論業界使用案例。
• 公告：加入或查看郵寄清單。
• Privacy Sandbox 開發人員支援服務：在 Privacy Sandbox 開發人員支援服務存放區提問並加入討論。
• Chromium：回報 Chromium 錯誤，詢問 Chrome 中進行的實作測試。