報表 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

報表 ID 可供 Protected Audience 買方和賣方函式使用
可選報表 ID 的供應情形

buyerReportingIdbuyerAndSellerReportingId 是無法選取的報表 ID,在興趣群組設定中定義,可供買方和賣方報表函式使用。買方和賣方報表函式只會針對得標廣告執行,且函式會接收為該得標廣告定義的報表 ID。

如未使用可選的報表 ID,買方報表函式會根據覆寫行為接收 buyerReportingIdbuyerAndSellerReportingId,賣方報表函式則會接收 buyerAndSellerReportingId。如果興趣群組設定中未定義 buyerReportingIdbuyerAndSellerReportingId,則 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

  • 如果同時定義 buyerAndSellerReportingIdbuyerReportingIdbuyerAndSellerReportingId 會覆寫 buyerReportingId,而 buyerAndSellerReportingId 會在 reportWin() 中提供。
  • 如果只定義 buyerReportingId,則可使用 buyerReportingId
  • 如果未定義 buyerAndSellerReportingIdbuyerReportingId,則可使用 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 季前,這項檢查不會納入廣告大小)。

buyerAndSellerReportingIdbuyerReportingId 都已定義

如果興趣群組設定中同時定義了 buyerAndSellerReportingIdbuyerReportingId

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 季前,這項檢查不會納入廣告大小)。

未定義 buyerAndSellerReportingIdbuyerReportingId

如果興趣群組設定中未定義任何報表 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 可供 Protected Audience 買方和賣方函式使用
可選報表 ID 的報表 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() 傳回,則除非 selectedBuyerAndSellerReportingIdbuyerAndSellerReportingId (如有) 與興趣群組擁有者、出價指令碼網址、轉譯網址和廣告大小 (至少在 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 的覆寫規則。瀏覽器會根據以下邏輯,決定要將 selectableBuyerAndSellerReportingIdsbuyerAndSellerReportingIdbuyerReportingId 和興趣群組名稱傳遞至 reportWin()

  • 如果出價傳回 selectedBuyerAndSellerReportingId,則 selectedBuyerAndSellerReportingIdbuyerAndSellerReportingId (如果在興趣群組中定義) 和 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

互動並分享意見回饋