定義目標對象資料

瞭解如何使用 Protected Audience API 建立興趣群組，藉此定義目標對象。請參閱開發人員指南，瞭解 Protected Audience API 的完整生命週期；如需關於瀏覽器記錄興趣群組的詳細提案，請參閱 Protected Audience API 說明。

如果您不是開發人員，請參閱「Protected Audience API 總覽」。

Protected Audience API 興趣群組

Protected Audience API 興趣群組代表有共同興趣的一群使用者，對應再行銷名單。每個 Protected Audience API 興趣群組都有擁有者。

興趣群組擁有者在 Protected Audience API 廣告競價中擔任買方。興趣群組的成員會儲存在瀏覽器和使用者的裝置上，不會與瀏覽器廠商或任何人共用。

API 函式

joinAdInterestGroup()

廣告主的需求端平台 (DSP) 或廣告客戶自行呼叫 navigator.joinAdInterestGroup()，要求瀏覽器將興趣群組加進瀏覽器的成員清單。

joinAdInterestGroup() 的呼叫背景資訊來源必須與興趣群組擁有者的來源相符，因此除非興趣群組擁有者的來源與目前文件的來源相同 (例如擁有興趣群組的網站)，否則必須透過 iframe 呼叫 joinAdInterestGroup() (例如來自需求端平台)。

「joinAdInterestGroup()」要求取得以下權限：

也就是說，如果沒有 dsp.example.com 授予權限，malicious.example 就無法為 dsp.example.com 擁有的興趣群組呼叫 joinAdInterestGroup()。

造訪網站的權限

您可以授予相同來源或跨來源的權限。根據預設，系統會從已造訪網站的相同來源發出 joinAdInterestGroup() 呼叫 (也就是與目前頁面的頂層頁框相同)。

應用實例

以下舉例說明使用者如何定義興趣群組，並要求瀏覽器加入群組。

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

傳遞至函式的 interestGroup 物件大小不得超過 50 KB，否則呼叫會失敗。第二個參數可指定興趣群組的持續時間，上限為 30 天。連續呼叫會覆寫先前儲存的值。

必要屬性

興趣群組只需要 owner 和 name 屬性：

屬性 範例 角色
owner https://dsp.example 興趣群組擁有者的來源。
name custom-bikes 興趣群組的名稱。

選用屬性

其餘屬性為選用屬性：

biddingLogicUrl1、2
範例：https://dsp.example/bid/custom-bikes/bid.js
角色：在 Worklet 中執行 JavaScript 出價網址的網址。
biddingWasmHelperUrl1、2
範例：https://dsp.example/bid/custom-bikes/bid.wasm
角色：來自 biddingLogicUrl 的 WebAssembly 程式碼網址。
updateUrl2
範例：https://dsp.example/bid/custom-bikes/update
角色：傳回 JSON 以更新興趣群組屬性的網址。 (請參閱「更新目標對象資料並重新整理廣告」一文)。
trustedBiddingSignalsUrl2
範例：https://dsp.example/trusted/bidding-signals
角色：向出價方信任的鍵/值服務提出鍵/值要求的基準網址。
trustedBiddingSignalsKeys
範例：['key1', 'key2' ...]
角色：向鍵/值信任的鍵/值服務提出要求的鍵。
userBiddingSignals
範例：{...}
角色：擁有者可在出價時使用的其他中繼資料。
ads1
範例：[bikeAd1, bikeAd2, bikeAd3]
角色：可能針對這個興趣群組顯示的廣告。
adComponents
範例：[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
角色：由多個部分組成的廣告的元件。

1 biddingLogicUrl 和 ads 為選用屬性，但必須搭配才能參與競價。在某些情況下，建立興趣群組時可能會缺少這些屬性。舉例來說，興趣群組擁有者想要將瀏覽器加入興趣群組，即廣告活動尚未放送、日後用於其他用途，或是廣告預算可能暫時用盡。

2 在目前 Protected Audience API 實作中，biddingLogicUrl、biddingWasmHelperUrl、updateUrl 和 trustedBiddingSignalsUrl 必須與擁有者俱有相同的來源。這可能不是長期限制，且 ads 和 adComponents 網址也沒有這類限制。

為興趣群組指定廣告

ads 和 adComponents 物件包含廣告素材網址，以及可在出價期間使用的任意中繼資料 (選用)。

例如：

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

leaveAdInterestGroup()

興趣群組擁有者可以要求從興趣群組中移除瀏覽器。瀏覽器會將興趣群組從成員清單中移除。

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

如果使用者返回的網站要求瀏覽器新增興趣群組，興趣群組擁有者可以呼叫 navigator.leaveAdInterestGroup() 函式，要求瀏覽器移除興趣群組。

廣告的程式碼也可以針對其興趣群組呼叫這個函式。

常見問題

就單一使用者而言，每個群組擁有者最多可以有幾組興趣群組？

Chrome 允許每位擁有者最多 1000 個興趣群組，以及最多 1000 位興趣群組擁有者。這些限制旨在當做防護機制，並非正常作業。

如何盡量提高符合 k-anon 門檻的興趣群組廣告？

透過公開說明中的附註，由於單一興趣群組可放送多則可能放送的廣告，因此每當有最多一個廣告做為「備用廣告」時，該集團就有機會重新出價爭取其中一則廣告，做為「備用廣告」。也就是說，未達 k-anonymity 門檻的小型專業廣告仍可選擇參與競價，而興趣群組也包括改為放送一般性更高的廣告，直到專屬廣告的目標對像人數夠多為止。

從策略的角度來看，您可以考慮以下幾點：

  • 若要讓新廣告開始放送，請在希望廣告顯示的情況下，開始對該廣告出價。您無須採取任何行動。
  • 如果您在新廣告不是 k-anon 時，便可使用備用廣告。備用廣告本身可能會不是 k-anon ，因此有時您可以考慮直接使用備用廣告出價。舉例來說，可能有 1% 的時間執行此動作 (例如正常等級)，確保備用廣告會超過門檻。

最近我們討論過其他可能可行的應用方式，如果您有一些此機制會引發問題的用途，請繼續參與公開對話，說明 API 可改進的地方。

所有 Protected Audience API 參考資料

可用的 API 參考指南如下：

Protected Audience API 說明也提供功能支援和限制的詳細資料。