定義目標對象資料

瞭解如何使用 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() (例如從 DSP)。

「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 KiB，否則呼叫會失敗。第二個參數會指定興趣群組的存續時間，上限為 30 天。後續呼叫會覆寫先前儲存的值。

必要屬性

興趣群組的必要屬性只有 owner 和 name：

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

選用屬性

其餘屬性為選用屬性：

biddingLogicUrl1、2
範例：https://dsp.example/bid/custom-bikes/bid.js
角色：在工作單元中執行的出價 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 個興趣群組擁有者。這些限制是為了提供防護措施，而非在正常運作時達到這些限制。

如何盡量放送符合 𝑘 匿名門檻的興趣群組廣告？

如公開說明所述，由於單一興趣群組可攜帶多個可能顯示的廣告，因此只要最偏好的廣告低於門檻，群組就有機會重新出價，將其他廣告做為「備用廣告」。也就是說，即使小型專業廣告仍低於 𝑘 匿名門檻，仍可選擇參與競價，且興趣群組有方法可回歸較為通用的廣告，直到專業廣告擁有足夠大的目標對象為止。

從策略角度來看，您可以考慮下列事項：

  • 如要開始放送新廣告，只要在您希望顯示廣告的情況下，開始對該廣告出價即可。你不需要採取任何其他行動。
  • 如果新廣告不是 𝑘-匿名，您可以使用備用廣告。備用廣告本身可能並非 𝑘 匿名，因此您可以考慮直接使用備用廣告出價。舉例來說，如果這是確保備援機制維持在門檻以上的合適程度，或許可以 1% 的時間這麼做。

最近有人討論其他運作方式，因此如果您有這個機制會造成問題的用途，請繼續參與公開討論，瞭解如何改善 API。

所有 Protected Audience API 參考資料

可用的 API 參考指南如下：

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