報表 ID

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

總覽

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

您可以透過報表 ID 回報廣告的 ID，並啟用交易等用途。

有三種報表 ID，分為兩種類型：

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

報表 ID 的運作方式會因是否使用可選取的報表 ID 而異。如果只使用無法選取的報表 ID，這些 ID 就只會在報表函式中提供。使用可選取的報表 ID (以及視需要使用不可選取的報表 ID) 時，所有已定義的 ID 也會顯示在 generateBid() 和 scoreAd() 中。

無法選取的報表 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}`);
}

在 reportResult() 中提供 ID 之前，系統會先檢查興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季前，廣告大小不會納入這項檢查) 的 k-匿名性。如果不是 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之前，系統會檢查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之前，系統會檢查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;
}

reportWin()在可供使用前，系統會檢查buyerAndSellerReportingId的 k-匿名性，檢查對象包括興趣群組擁有者、出價指令碼網址、顯示網址和廣告尺寸 (至少在 2025 年第 1 季前，廣告尺寸不會納入這項檢查)。

未定義 buyerAndSellerReportingId 和 buyerReportingId

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

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-匿名性，並考量興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小)。

可選取的報表 ID

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

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

如果同時使用可選取的報表 ID 和不可選取的報表 ID，其行為會與上一節所述的工作流程不同。與只能在報表函式中使用的不可選取報表 ID 初始行為不同，可選取報表 ID 可讓不可選取報表 ID 在 generateBid() 和 scoreAd() 中使用。

興趣群組

可選取的報表 ID 欄位 - selectableBuyerAndSellerReportingIds - 是買方在廣告興趣群組中定義的字串陣列。您也可以一併定義無法選取的報表 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 會與其他已定義的報表 ID 一併顯示在 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
  };
}

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

如果 selectedbuyerAndSellerReportingId 的傳回值與 buyerAndSellerReportingId (如有)、buyerReportingId (如有)、興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季前，廣告大小不會納入這項檢查) 共同符合 k-anonymous，則selectedbuyerAndSellerReportingId 的出價可能只會贏得競價。

賣家廣告評分

對賣家而言，買家從 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，且 generateBid() 傳回了 selectedBuyerAndSellerReportingId，則除非 selectedBuyerAndSellerReportingId 和 buyerAndSellerReportingId (如有) 與興趣群組擁有者、出價指令碼網址、顯示網址和廣告大小 (至少在 2025 年第 1 季前，廣告大小不會納入這項檢查) 都是 k 匿名，否則無法贏得競價，且系統不會為該出價執行 reportResult()。因此，如果使用 selectedBuyerAndSellerReportingId 的值呼叫 reportResult()，表示報表 ID 通過 k-anonymity 檢查，且所有定義的報表 ID 都會在 reportResult() 中提供。

買方報表

如果興趣群組設定中定義了 selectableBuyerAndSellerReportingIds，且 generateBid() 傳回了 selectedBuyerAndSellerReportingId，則興趣群組設定中定義的所有報表 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，請參閱「Protected Audience 說明」的「報表 ID」一節。
• GitHub：在 API 存放區的問題中提出問題並追蹤討論。
• W3C：在 WICG 通話中討論產業應用實例。
• 公告：加入或查看郵寄清單。
• Privacy Sandbox 開發人員支援：在 Privacy Sandbox 開發人員支援存放區提出問題並參與討論。
• Chromium：提出 Chromium 錯誤，詢問可在 Chrome 中測試的實作項目。