本頁面由 Cloud Translation API 翻譯而成。

報表 ID

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

總覽

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

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

報表 ID 可供 Protected Audience 買方和賣方函式使用 — 報表 ID 可用性

報表 ID 分為兩種類型：

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

報表 ID 的運作方式會因是否使用可選報表 ID 而有所不同。如果只使用不可選取的報表 ID，這些 ID 只會在報表函式中顯示。使用可選報表 ID 時，系統會視需要加入不可選報表 ID，並在 generateBid() 和 scoreAd() 中提供所有定義的 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',
  }]
});

賣家報表

在賣方回報階段，buyerAndSellerReportingId 值會提供給 reportResult()：

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

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

在 ID 可供 reportResult() 使用之前，系統會檢查 ID 是否符合 k-匿名性，並與興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小搭配使用 (至少在 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 會與興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小一起進行 k-anonymity 檢查 (至少在 2025 年第 1 季前，廣告大小不會納入這項檢查)。如果 k 匿名性檢查失敗，reportWin() 仍會執行，但函式內不會提供回報 ID 值。

僅定義 `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 匿名性檢查 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小)。

僅定義 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 匿名性檢查 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小)。

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

未定義 `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) 是否符合 k 匿名性，並與興趣群組擁有者、出價指令碼網址、轉譯網址和廣告大小進行比對 (至少在 2025 年第 1 季前，系統不會檢查廣告大小)。

可選報表 ID

選取的報表 ID 可讓買方在出價產生期間選取 ID，瀏覽器會將所選值提供給 scoreAd() 和報表函式。selectableBuyerAndSellerReportingIds 值 (字串陣列) 會提供給 generateBid()，買家可以將所選 ID 以 selectedBuyerAndSellerReportingId 的形式傳回。

generateBid() 和 scoreAd() 函式會針對興趣群組設定中定義的每個廣告執行，並接收每個廣告的報表 ID。買方和賣方報表函式只會針對得標廣告執行，且函式會接收為該得標廣告定義的報表 ID。

當非選取式報表 ID 與選取式報表 ID 搭配使用時，其行為會與前一個部分所述的工作流程不同。與無法選取報表 ID 的初始行為不同，可選取的報表 ID 可讓無法選取的報表 ID 在 generateBid() 和 scoreAd() 中使用。

進行測試。

興趣群組

可選報表 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，則 generateBid() 會與已定義的其他報表 ID 一併提供 selectableBuyerAndSellerReportingIds。

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

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

如果出價的 selectedbuyerAndSellerReportingId 傳回值可能只會贏得競價，前提是 selectedbuyerAndSellerReportingId 的值與 buyerAndSellerReportingId (如有)、buyerReportingId (如有)、興趣群組擁有者、出價指令碼網址、轉譯網址和廣告大小共同採用 k-匿名機制 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小)。

generateBid()

賣方廣告評分

對於賣方而言，買方從 generateBid() 傳回的 selectedBuyerAndSellerReportingId 會在 scoreAd() 中提供，如果在興趣群組設定中定義了 buyerAndSellerReportingId，也會一併提供。

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() 傳回，則除非 selectedBuyerAndSellerReportingId 和 buyerAndSellerReportingId (如有) 與興趣群組擁有者、出價指令碼網址、轉譯網址和廣告大小 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小) 皆為 k-anonymous，否則無法贏得競價，且 reportResult() 也不會針對該出價執行。因此，如果呼叫 reportResult() 時傳遞 selectedBuyerAndSellerReportingId 的值，表示報表 ID 已通過 k 匿名性檢查，且 reportResult() 內會提供所有定義的報表 ID。

買方報表

如果 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) `selectedBuyerAnd SellerReportingIds` 2) `buyerAndSeller ReportingId` (如果已定義) 3) `buyerReportingId` (如果已定義)	1) `selectedBuyerAnd 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 中測試可用的實作方式。

報表 ID

總覽

無法選取的報表 ID

興趣群組中的報表 ID

賣家報表

買方報表

僅定義 buyerReportingId

僅定義 buyerAndSellerReportingId

buyerAndSellerReportingId 和 buyerReportingId 都已定義

未定義 buyerAndSellerReportingId 或 buyerReportingId

可選報表 ID

興趣群組

產生買方出價

賣方廣告評分

賣家報表

買方報表

覆寫規則

互動並分享意見回饋

僅定義 `buyerReportingId`

`buyerAndSellerReportingId` 和 `buyerReportingId` 都已定義

未定義 `buyerAndSellerReportingId` 或 `buyerReportingId`