報表 ID

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

總覽

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

您可以使用報表 ID 回報廣告 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-anonymity 檢查 (至少在 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-anonymity 檢查 (至少在 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-anonymity 檢查 (至少在 2025 年第 1 季前，這項檢查不會納入廣告大小)。

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

可選報表 ID

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

generateBid() 和 scoreAd() 函式會針對興趣群組設定中定義的每個廣告執行，並接收每個廣告的報表 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 一併提供。

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() 傳回的 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 匿名，否則無法贏得競價，且 reportResult() 也不會針對該出價執行。因此，如果呼叫 reportResult() 時傳入 selectedBuyerAndSellerReportingId 的值，表示報表 ID 已通過 k-anonymity 檢查，且 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，請參閱 Protected Audience 說明中的「報表 ID」一節。
• GitHub：在 API 存放區提出問題，並追蹤討論中的相關問題。
• W3C：在 WICG 會議中討論產業用途。
• 公告：加入或查看郵寄清單。
• Privacy Sandbox 開發人員支援服務：在 Privacy Sandbox 開發人員支援服務存放區提問並加入討論。
• Chromium：提交 Chromium 錯誤，詢問有關在 Chrome 中測試可用的實作方式。