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

在競價中出價購買廣告版位

身為廣告買家 (DSP 和廣告主)，您可能會想在發布商網站上參與 Protected Audience 廣告競價，以便向您在廣告主網站上定義的興趣群組放送廣告。參與 Protected Audience 競價後，您就能在其他網站上觸及已識別的顧客，同時兼顧隱私權。

在 Protected Audience 競價中，您會提供產生出價的邏輯，瀏覽器則會使用該邏輯計算出價。這與其他競價架構不同，您不必提供邏輯，而是直接出價。

您可以在 generateBid() JavaScript 函式中提供出價生成邏輯，並將檔案代管在伺服器上。將使用者新增至興趣群組時，這個檔案的位置會以 biddingLogicUrl 形式傳遞至興趣群組設定。

競價期間，瀏覽器會擷取 biddingLogicUrl 欄位中指定的出價邏輯，並在安全隔離的環境中，為每個興趣群組執行 generateBid() 函式，該環境與外部環境的通訊受到限制。執行 generateBid() 時，瀏覽器會將信號做為引數傳遞至函式。這些信號包含來自不同來源的各種資訊，例如發布商的第一方資料、賣方資料、即時資料等。您可以使用這些信號計算出價，而值會從 generateBid() 呼叫傳回。出價送出後，瀏覽器會對每項出價執行賣方的評分邏輯，計算賣方的吸引力分數。

`generateBid()`

以下說明 generateBid() 函式的引數，以及函式傳回的出價結構：


generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

引數

generateBid() 會採用下列引數：

引數	角色
`interestGroup`	廣告買方傳遞的物件。興趣群組可能會更新為 `dailyUpdateUrl`。
`auctionSignals`	賣家傳遞至 `navigator.runAdAuction()` 的競價設定引數屬性。這項資訊提供網頁內容的相關資訊 (例如廣告大小和發布商 ID)、競價類型 (最高價或次高價) 和其他中繼資料。
`perBuyerSignals`	賣方傳遞的 auction config 引數屬性。如果賣方是 SSP，會向買方伺服器發出即時出價呼叫，並將回應傳回，或如果發布商網頁直接聯絡買方伺服器，即可從買方伺服器取得網頁的內容相關信號。如果是，買家可能會想檢查 `generateBid()` 內這些信號的加密簽章，以防遭到竄改。
`trustedBiddingSignals`	物件，其鍵是興趣群組的 `trustedBiddingSignalsKeys`，值則會在 `trustedBiddingSignals` 要求中傳回。
`browserSignals`	瀏覽器建構的物件，可能包含網頁內容的相關資訊 (例如目前網頁的 `hostname`，否則賣家可能會偽造)，以及興趣群組本身的資料 (例如群組先前贏得競價的記錄，以便在裝置上設定頻率上限)。
`directFromSellerSignals`	來自特定賣方的信號，與 `auctionSignals` 和 `sellerSignals` 不同，後者可來自執行 `runAdAuction` 時情境中的任何參與者。

瀏覽器信號

browserSignals 物件具有下列屬性：

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

屬性	說明
`topWindowHostname`	發出 `runAdAuction()` 呼叫的主機名稱。
`seller`	提交出價的賣家。在元件競價中，這個值是元件賣方。
`topLevelSeller`	元件競價中的最高層級賣方，僅出現在元件競價中。
`requestedSize`	`requestedSize` 屬性會建議競價的影格大小。賣家會在競價設定中設定要求的大小，出價方則可在 `generateBid()` 中取得該值。競價中的競價者可能會為廣告選擇不同大小的內容，而系統會將產生的廣告大小縮放至元素容器大小內。
`joinCount`	`joinCount` 欄位代表在過去 30 天內，這個裝置加入這個興趣群組的次數，且興趣群組持續儲存 (也就是說，裝置上儲存的興趣群組沒有因離開或成員資格到期而出現間隔)。
`recency`	`recency` 欄位是這部裝置加入這個興趣群組至今的時間長度 (以分鐘為單位)
`bidCount`	興趣群組提交出價的次數。
`prevWinsMs`	`prevWinMs` 欄位包含興趣群組的勝出廣告，以及自上次勝出以來經過的時間 (以毫秒為單位)。請注意，這裡的廣告物件只包含 `renderURL` 和中繼資料欄位。
`wasmHelper`	以興趣群組的 `biddingWasmHelperURL` 為基礎的 WebAssembly.Module 物件。
`dataVersion`	買方鍵/值服務回應中的 Data-Version 值。
`adComponentsLimit`	最多可傳回 `generateBid()` 個廣告元件

計算出價

如要計算出價值，generateBid() 中的程式碼可以使用函式參數的屬性。

例如：

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

退回出價

generateBid() 會傳回具有下列屬性的物件：

屬性	角色
`ad`	廣告的任意中繼資料，例如賣方希望瞭解的出價或廣告素材資訊。賣家會在競價和決策邏輯中使用這項資訊。
`adCost`	用來將報表廣告主點擊或轉換費用從 generateBid 傳遞至 reportWin 的數值。這個數字的精確度受限於 8 位數的尾數和 8 位數的指數，且所有四捨五入作業都是隨機執行。
`adComponents`	最多 20 個元件的選用清單，適用於由多個部分組成的廣告，取自傳遞至 `navigator.joinAdInterestGroup()` 的興趣群組引數的 adComponents 屬性。
`allowComponentAuction`	布林值，指出這個出價是否可用於元件競價。如未指定，則預設為「false」。
`bid`	將進入競價的數值出價。賣方必須能夠比較不同買方的競價，因此競價必須以賣方選擇的單位 (例如「每千次曝光出價」) 表示。如果出價為零或負數，這個興趣群組就不會參與賣方的競價。買方可透過這項機制，針對廣告的顯示位置實作任何廣告主規則。
`bidCurrency`	出價的貨幣，用於檢查貨幣。
`render`	字典，說明這個出價贏得競價時應算繪的廣告素材。包括： `url`：廣告素材的網址。 `width`：廣告素材的寬度。系統會比對這個大小與興趣群組中的聲明，並代入廣告素材網址中任何廣告大小巨集。當廣告載入封閉框架時，封閉框架的內部框架 (即廣告素材可見的大小) 會凍結為這個大小，且無法看到嵌入器對框架大小所做的變更。 `height`：廣告素材的高度。詳情請參閱`width`。
`modelingSignals`	傳遞至 `reportWin()` 的 0 到 4095 整數 (12 位元)，並進行加噪處理，如加噪和分組機制所述。系統會忽略無效值 (例如負值、無限值和 `NaN` 值)，且不會傳遞這些值。系統只會傳遞最低的 12 位元。買方可以使用 `generateBid()` 函式中提供的信號，包括在 `userBiddingSignals` 建立興趣群組時擷取的第一方買方資料，推導出傳遞至買方得標報表函式的值，以利訓練 ML 模型。